Local semantic code search for Cursor and Claude Code via MCP.

dev-agent indexes your codebase and provides 9 MCP tools to AI assistants. Instead of AI tools grepping through files, they can ask conceptual questions like "where do we handle authentication?"

• dev_search — Semantic code search by meaning
• dev_refs — Find callers/callees of functions
• dev_map — Codebase structure with change frequency
• dev_history — Semantic search over git commits
• dev_plan — Assemble context for GitHub issues
• dev_inspect — Inspect files (compare similar code, check patterns)
• dev_gh — Search GitHub issues/PRs semantically
• dev_status / dev_health — Monitoring

We benchmarked dev-agent against baseline Claude Code across 5 task types:

Trade-offs: Faster but sometimes less thorough. Best for implementation tasks and codebase exploration. For deep debugging, baseline Claude may read more files.

Good fit:

• Large or unfamiliar codebases
• Implementation tasks ("add a feature like X")
• Exploring how code works
• Reducing AI API costs

Less useful:

• Small codebases you already know well
• Deep debugging sessions
• When thoroughness matters more than speed

# Install globally
npm install -g dev-agent

# Index your repository (initial indexing can take 5-10 minutes for large codebases)
cd /path/to/your/repo
dev index .

# Install MCP integration
dev mcp install --cursor  # For Cursor IDE
dev mcp install           # For Claude Code

# Keep index up to date (fast incremental updates)
dev update

# That's it! AI tools now have access to dev-agent capabilities.

When integrated with Cursor or Claude Code, dev-agent provides 9 powerful tools:

Natural language search with rich results including code snippets, imports, and relationships.

Find authentication middleware that handles JWT tokens

Features:

• Code snippets included (not just file paths)
• Import statements for context
• Caller/callee hints
• Progressive disclosure based on token budget

Query what calls what and what is called by what.

Find all callers of the authenticate function
Find what functions validateToken calls

Features:

• Bidirectional queries (callers/callees)
• File paths and line numbers
• Relevance scoring

Get a high-level view of repository structure with change frequency.

Show me the codebase structure with depth 3
Focus on the packages/core directory
Show hot areas with recent changes

Features:

• Directory tree with component counts
• Hot Paths: Most referenced files
• Change Frequency: 🔥 Hot (5+ commits/30d), ✏️ Active (1-4/30d), 📝 Recent (90d)
• Smart Depth: Adaptive expansion based on density
• Signatures: Function/class signatures in exports

Example output:

# Codebase Map

## Hot Paths (most referenced)
1. `packages/core/src/indexer/index.ts` (RepositoryIndexer) - 47 refs
2. `packages/core/src/vector/store.ts` (LanceDBVectorStore) - 32 refs

## Directory Structure

└── packages/ (195 components)
    ├── 🔥 core/ (45 components) — 12 commits in 30d
    │   └── exports: function search(query): Promise<Result[]>, class RepositoryIndexer
    ├── ✏️ mcp-server/ (28 components) — 3 commits in 30d
    │   └── exports: class MCPServer, function createAdapter(config): Adapter

Semantic search over git commit history.

Find commits about authentication token fixes
Show history for src/auth/middleware.ts

Features:

• Semantic search: Find commits by meaning, not just text
• File history: Track changes with rename detection
• Issue/PR refs: Extracted from commit messages
• Token-budgeted output

Assemble rich context for implementing GitHub issues.

Assemble context for issue #42

Returns:

• Full issue with comments
• Relevant code snippets from semantic search
• Related commits from git history (new in v0.4)
• Detected codebase patterns (test naming, locations)
• Metadata (tokens, timing)

Note: This tool no longer generates task breakdowns. It provides comprehensive context so the AI assistant can create better plans.

Inspect files for pattern analysis. Finds similar code and compares patterns (error handling, type coverage, imports, testing).

Inspect src/auth/middleware.ts for patterns
Check how src/hooks/useAuth.ts compares to similar hooks

Pattern Categories:

• Import style (ESM vs CJS)
• Error handling (throw vs result types)
• Type coverage (full, partial, none)
• Test coverage (co-located test files)
• File size relative to similar code

View indexing status, component health, and repository information.

Search issues and PRs with semantic understanding.

Find authentication-related bugs
Search for performance issues in closed PRs

Check MCP server and component health.

• 📦 Works 100% offline
• 🔐 Your code never leaves your machine
• ⚡ Fast local embeddings with all-MiniLM-L6-v2

• 🛡️ Rate limiting (100 req/min burst)
• 🔄 Retry logic with exponential backoff
• ⚡ Incremental indexing (only processes changed files)
• 💚 Health monitoring
• 🧹 Memory-safe (circular buffers)
• ✅ 1300+ tests

• 🪙 Progressive disclosure based on budget
• 📊 Token estimation in results
• 🎯 Smart depth for codebase maps

• Node.js v22 LTS or higher
• pnpm v8.15.4 or higher
• GitHub CLI (for GitHub features)

npm install -g dev-agent

git clone https://github.com/lytics/dev-agent.git
cd dev-agent
pnpm install
pnpm build
cd packages/dev-agent
npm link

# Index everything (code, git history, GitHub) - can take 5-10 min for large codebases
dev index .
dev index . --no-github               # Skip GitHub indexing

# Incremental updates (only changed files) - much faster, typically seconds
dev update                            # Fast incremental reindexing
dev update -v                         # Verbose output showing what changed

# Semantic search
dev search "how do agents communicate"
dev search "error handling" --threshold 0.3

# Git history search
dev git search "authentication fix"   # Semantic search over commits
dev git stats                         # Show indexed commit count

# GitHub integration
dev github index                          # Index issues and PRs (also done by dev index)
dev github search "authentication bug"    # Semantic search

# View statistics
dev stats

# MCP management
dev mcp install --cursor              # Install for Cursor
dev mcp install                       # Install for Claude Code
dev mcp list                          # List configured servers

Control scanning and indexing performance using environment variables:

# Global concurrency setting (applies to all operations)
export DEV_AGENT_CONCURRENCY=10

# Language-specific concurrency settings
export DEV_AGENT_TYPESCRIPT_CONCURRENCY=20  # TypeScript file processing
export DEV_AGENT_INDEXER_CONCURRENCY=5      # Vector embedding batches

# Index with custom settings
dev index .

Auto-detection: If no environment variables are set, dev-agent automatically detects optimal concurrency based on your system's CPU and memory.

Recommended settings:

Current language support:

• TypeScript/JavaScript: Full support (.ts, .tsx, .js, .jsx, .mjs, .cjs)
• Go: Full support (.go)

To add new languages, see LANGUAGE_SUPPORT.md.

Indexing too slow:

# Note: Initial indexing can take 5-10 minutes for mature codebases (4k+ files)
# Try increasing concurrency (if you have enough memory)
export DEV_AGENT_CONCURRENCY=20
dev index .

Out of memory errors:

# Reduce concurrency
export DEV_AGENT_CONCURRENCY=5
export DEV_AGENT_TYPESCRIPT_CONCURRENCY=5
export DEV_AGENT_INDEXER_CONCURRENCY=2
dev index .

Search results are outdated:

# Update index with recent file changes
dev update
# Or do a full reindex if needed
dev index .

Go scanner not working:

# Check if WASM files are bundled (after installation/build)
ls -la ~/.local/share/dev-agent/dist/wasm/tree-sitter-go.wasm
# If missing, try reinstalling or rebuilding from source

dev-agent/
├── packages/
│   ├── core/           # Scanner, vector storage, indexer
│   ├── cli/            # Command-line interface
│   ├── subagents/      # Planner, explorer, PR agents
│   ├── mcp-server/     # MCP protocol server + adapters
│   └── integrations/   # Claude Code, VS Code
├── docs/               # Documentation
└── website/            # Documentation website

• TypeScript (strict mode)
• ts-morph / TypeScript Compiler API (TypeScript/JS analysis)
• tree-sitter WASM (Go analysis, extensible to Python/Rust)
• LanceDB (embedded vector storage)
• @xenova/transformers (local embeddings)
• MCP (Model Context Protocol)
• Turborepo (monorepo builds)
• Vitest (1500+ tests)

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Lint and format
pnpm lint
pnpm format

# Type check
pnpm typecheck

• v0.6.0 - Go Language Support & Performance Improvements
  • Go scanner with tree-sitter WASM (functions, methods, structs, interfaces, generics)
  • Configurable concurrency via environment variables (DEV_AGENT_*_CONCURRENCY)
  • Auto-detection of optimal performance settings based on system resources
  • Enhanced error handling and user feedback across all scanners
  • Improved Go scanner with runtime WASM validation and better error messages
  • Parallel processing optimizations for TypeScript scanning and indexing
  • Indexer logging with --verbose flag and progress spinners
  • Go-specific exclusions (*.pb.go, *.gen.go, mocks/, testdata/)
  • Comprehensive language support documentation (LANGUAGE_SUPPORT.md)
  • Build-time validation to prevent silent WASM dependency failures
  • Infrastructure for future Python/Rust support
• v0.4.0 - Intelligent Git History release
  • New dev_history tool for semantic commit search
  • Enhanced dev_map with change frequency indicators (🔥 hot, ✏️ active)
  • Enhanced dev_plan with related commits from git history
  • New GitIndexer and LocalGitExtractor in core
• v0.3.0 - Context Quality release
  • New dev_refs tool for relationship queries
  • Enhanced dev_map with hot paths, smart depth, signatures
  • Refactored dev_plan to context assembly
• v0.2.0 - Richer search results with snippets and imports
• v0.1.0 - Initial release

Contributions welcome! Please follow conventional commit format and include tests.

See CONTRIBUTING.md for guidelines.

MIT