codefocus

AST-powered code search that returns structured, ranked context for LLM agents.

Tree-sitter parses your codebase into a SQLite graph database. Queries combine full-text search, symbol-aware graph traversal, and PageRank scoring to return the most relevant code sections within a token budget. One call replaces multiple grep/read round-trips.

Install

npm install -g @ngommans/codefocus
# or use directly
npx @ngommans/codefocus

Requires Node 18+.

Quick start

# Index your project (creates .codefocus/index.db)
codefocus index --root .

# Search for relevant code context
codefocus query "handleSync" --budget 8000

# Get a high-level codebase overview
codefocus map --budget 2000

# Find a specific symbol
codefocus find "MyClass" --kind class

# Show dependency graph for a file
codefocus graph src/services/auth.ts

Commands

| Command | Description | |---------|-------------| | index | Parse the codebase with tree-sitter and store symbols in SQLite | | query | Search and return ranked, budget-constrained code context | | find | Quick symbol lookup by name and optional kind filter | | graph | Show dependency graph for a file or symbol | | map | High-level codebase overview ranked by PageRank | | serve | Start MCP server (stdio transport) |

Claude Code integration

MCP server (recommended)

Add .mcp.json to your project root:

{
  "mcpServers": {
    "codefocus": {
      "command": "npx",
      "args": ["--yes", "@ngommans/codefocus", "serve", "--root", "."]
    }
  }
}

Claude Code auto-discovers the MCP server and exposes query, find, graph, and map as tools with sub-10ms response times.

Auto-indexing hook

Add .claude/hooks.json to keep the index fresh:

{
  "hooks": {
    "SessionStart": [{
      "command": "npx --yes @ngommans/codefocus index --root .",
      "timeout": 30000
    }]
  }
}

How it works

1. Index — tree-sitter parses TypeScript/JavaScript files, extracting symbols (functions, classes, interfaces, types), imports, and cross-file references into a SQLite database with FTS5 full-text search.

2. Query — combines symbol-name matching, FTS5 content search, and graph expansion (BFS along import/reference edges). Results are ranked by match strength, term frequency, symbol proximity, and PageRank. Relevance thresholds prune noise automatically.

3. Output — ranked code sections with YAML front matter, constrained to a token budget. One query replaces 3-7 grep/read cycles.

Configuration

Tuning parameters can be customized per-project via .codefocus/config.json:

{
  "scoring": {
    "scoreFloorRatio": 0.20,
    "elbowDropRatio": 0.60,
    "minMarginalValue": 0.00003,
    "symbolProximityBoost": 1.5,
    "defaultBudget": 8000,
    "defaultDepth": 2
  }
}

License

MIT