npm package: @ngommans/codefocus
Description: Smart code context aggregator — AST-powered search that returns structured, ranked code context for LLM agents
Author: Nick Gommans
Latest version: 1.0.0

# codefocus

[![CI](https://github.com/ngommans/codefocus/actions/workflows/ci.yml/badge.svg)](https://github.com/ngommans/codefocus/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/@ngommans/codefocus)](https://www.npmjs.com/package/@ngommans/codefocus)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
[![Node 18+](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)

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

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

Requires Node 18+.

## Quick start

```bash
# 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:

```json
{
  "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:

```json
{
  "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`:

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

## License

MIT