Architecture

dev-agent is built as a TypeScript monorepo with specialized packages for different concerns.

System Overview


┌─────────────────────────────────────────────────────────────────────┐
│                         AI Tools                                    │
│                 (Cursor / Claude Code / VS Code)                    │
└─────────────────────────┬───────────────────────────────────────────┘
                          │ Model Context Protocol (MCP)
┌─────────────────────────▼───────────────────────────────────────────┐
│                      MCP Server                                     │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                    Adapter Registry                          │    │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │    │
│  │  │ Search   │ │  Plan    │ │ Explore  │ │  GitHub  │  ...   │    │
│  │  │ Adapter  │ │ Adapter  │ │ Adapter  │ │ Adapter  │        │    │
│  │  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘        │    │
│  └───────┼────────────┼────────────┼────────────┼───────────────┘    │
│          │            │            │            │                   │
│  ┌───────▼────────────▼────────────▼────────────▼───────────────┐   │
│  │                    Subagent Coordinator                       │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐                      │   │
│  │  │ Planner  │ │ Explorer │ │ PR Agent │                      │   │
│  │  └──────────┘ └──────────┘ └──────────┘                      │   │
│  └──────────────────────────────────────────────────────────────┘   │
└─────────────────────────┬───────────────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────────────┐
│                         Core                                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │   Scanner    │  │   Indexer    │  │   GitHub     │              │
│  │  (AST Parse) │  │  (Embeddings)│  │  Integration │              │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘              │
│         │                 │                 │                       │
│  ┌──────▼─────────────────▼─────────────────▼───────────────────┐   │
│  │                    Vector Storage                             │   │
│  │                (Antfly — hybrid search)                       │   │
│  └──────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘

Packages

@prosdevlab/dev-agent-core

The foundation layer providing:

Scanner — Multi-language AST parsing:
- TypeScript/JavaScript via ts-morph
- Go via tree-sitter WASM
- Markdown via remark
Indexer — Sends code components to Antfly for embedding and storage
Vector Storage — Antfly for hybrid search (BM25 + vector + RRF)
GitHub Integration — Fetches and indexes issues/PRs via GitHub CLI

@prosdevlab/dev-agent-cli

Command-line interface:


dev index              # Index repository
dev mcp install          # Install MCP integration
dev github index             # Index GitHub issues/PRs
dev status               # Check indexing status

@prosdevlab/dev-agent-mcp

MCP server with tool adapters:

AdapterRegistry — Manages tool registration and execution
Built-in Adapters — Search, Plan, Explore, GitHub, Status, Health
Rate Limiting — Token bucket algorithm (100 req burst)
Retry Logic — Exponential backoff with jitter

@prosdevlab/dev-agent-subagents

Specialized AI agents:

PlannerAgent — Generates implementation plans from issues
ExplorerAgent — Code pattern analysis and relationship mapping
PRAgent — PR management and review assistance
Coordinator — Routes tasks to appropriate agents

@prosdevlab/kero

Centralized logging:

Multiple log levels (debug, info, warn, error)
Console and file transports
JSON and pretty formatters
Structured metadata

Supported Languages

Language	Scanner	Features
TypeScript/JavaScript	ts-morph	Functions, classes, interfaces, JSDoc
Go	tree-sitter WASM	Functions, methods, structs, interfaces, generics
Markdown	remark	Documentation sections, code blocks

Key Technologies

Component	Technology	Purpose
Language	TypeScript (strict)	Type safety
Build	Turborepo	Monorepo orchestration
Testing	Vitest	1500+ tests
Linting	Biome	Fast linting/formatting
Search	Antfly	Hybrid search (BM25 + vector + RRF)
Embeddings	Termite (via Antfly)	Local ONNX inference (bge-small-en-v1.5)
Protocol	MCP	AI tool integration
TS/JS Parser	ts-morph	TypeScript Compiler API
Go Parser	tree-sitter WASM	Fast, portable parsing

Data Flow

Indexing Flow


Source Code
    │
    ▼
┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  Glob    │ ──▶ │  Parse   │ ──▶ │ Extract  │ ──▶ │  Store   │
│  Files   │     │   AST    │     │Components│     │ (Antfly) │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
                                          Antfly auto-embeds via Termite

Query Flow


User Query: "Where is auth handled?"
    │
    ▼
┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  Hybrid  │ ──▶ │BM25+Vec  │ ──▶ │  RRF     │ ──▶ │  Format  │
│  Query   │     │  Search  │     │  Fusion  │     │  Output  │
└──────────┘     └──────────┘     └──────────┘     └──────────┘

Storage

Data is stored locally by Antfly (default ~/.antfly/) and dev-agent config in ~/.dev-agent/.

Antfly manages its own storage, indexes, and embeddings. dev-agent creates three tables:

dev-agent-{project}-code — code components
dev-agent-{project}-git — git commit history
dev-agent-{project}-github — GitHub issues/PRs

Security

100% Local — No data sent to external services
No Cloud — All processing happens on your machine
Embeddings — Generated locally via Antfly’s Termite engine (ONNX)
GitHub Data — Fetched via authenticated GitHub CLI