srcpilot

Deterministic code intelligence for AI coding agents. srcpilot parses your repo with tree-sitter, stores a rich graph in a local SQLite index, and answers structural questions about your codebase without embeddings, vector stores, or any model in the analysis loop.

Use it to answer questions like:

• what symbols exist and where they live
• what file to open first given a compile error or test failure
• why one file outranks another as a likely root cause
• where duplicate or competing implementations are hiding
• what will break if you change a symbol
• how HTTP routes, ORM queries, and execution flows connect across the repo
• which module clusters make up the codebase and how to navigate between them

Quick Start

cd /path/to/your/project
npx -y srcpilot init
npx -y srcpilot setup

Requires Node 22.13 or newer.

init creates .srcpilot/db.sqlite and indexes the repo. setup wires srcpilot into your AI tool's rules directory. Pathless commands automatically anchor to the nearest ancestor containing .srcpilot, so you can run srcpilot map, srcpilot find, or srcpilot overview from any nested directory inside an indexed repo.

What Gets Indexed

srcpilot index parses every source file and builds a multi-layer graph in .srcpilot/db.sqlite:

Symbols and structure Files, functions, classes, interfaces, and type aliases with their locations, kinds, and export status.

Import graph Every import edge between files, with fan-in and fan-out metrics. Runtime fan-in and entrypoint detection are tracked separately. Module communities are derived from the import graph using label-propagation clustering, grouping related files into named clusters.

Call graph Function-to-function call edges with confidence scores: same-file calls score 1.0, calls to imported symbols score 0.9, and unresolved calls score 0.6. Class hierarchy — extends and implements relations — is stored as symbol relations in the same graph.

HTTP routes Method, path, handler, middleware, and framework for each route. Supported frameworks: Express, Koa, Hono, Next.js, FastAPI, Flask, and Go net/http.

Execution flows Entry-point-to-terminal BFS call paths are stored so you can query the full execution flow from any entry point.

ORM and database queries Query locations, models, operations, and ORM types for Prisma, Sequelize, TypeORM, Mongoose, SQLAlchemy, GORM, and raw SQL.

Staleness tracking After indexing, the current commit hash is stored. Every subsequent query compares HEAD to the stored hash and warns if the index is behind. Pass --no-stale-check to suppress the warning.

File roles Each file is classified as runtime, test, editor, generated, vendor, mock, or script. Role classification drives ranking demotion and --include-role / --exclude-role filtering.

CLI Commands

Core

| Command | Purpose | |---------|---------| | srcpilot init | Initialize index in the current project | | srcpilot index [path] | Full project index (--auto for background daemon) | | srcpilot reindex <path> | Re-index a single file | | srcpilot doctor | Health check — shows what is indexed and flags issues |

Navigation and Search

| Command | Alias | Purpose | |---------|-------|---------| | srcpilot find-symbol <name> | find | Find functions, classes, and types by name | | srcpilot find-usages <name> | usages | Find files that import a symbol | | srcpilot file-overview <path> | overview | List all symbols defined in a file | | srcpilot related-files <path> | related | Files connected by import, call graph, or test relation | | srcpilot navigate <query> | | Multi-channel search across symbols, files, and routes | | srcpilot map [path] | | Project overview from the saved index (--depth, --focus, --symbols) |

Judgment

These commands use the ranked decision layer. Results are deterministic and graph-backed — not embedding similarity.

| Command | Alias | Purpose | |---------|-------|---------| | srcpilot why <query> | | Rank likely root nodes, owners, and ambiguity traps | | srcpilot next <query> | | Rank the best files to open first | | srcpilot ambiguities [query] | | Duplicate names, role splits, and collision risks | | srcpilot implementations <symbol> | | Competing implementations of a concept | | srcpilot change-impact <symbol> | impact | Direct dependents, behavioral dependents, suggested tests, risk level | | srcpilot context-budget | budget | Files ranked by graph-aware centrality | | srcpilot api-surface | exports | All exported symbols | | srcpilot dead-code | dead | Unused exports | | srcpilot circular-deps | cycles | Circular import chains |

Graph Intelligence

| Command | Purpose | |---------|---------| | srcpilot trace <file> | BFS import graph traversal (--direction deps\|dependents, --depth, --json) | | srcpilot detect-changes | Files changed since the last index | | srcpilot routes | Query indexed HTTP routes (--method, --path, --framework, --json) | | srcpilot flows | Execution flows from entry points (--depth, --min-length, --limit, --json) | | srcpilot communities | Module clusters from label-propagation (--json) | | srcpilot shape-check | Detect handler return shape vs consumer access mismatches | | srcpilot rename <old> <new> | Confidence-scored multi-file rename plan (--dry-run, --execute, --include-uncertain, --json) | | srcpilot db-queries | ORM and raw SQL queries (--model, --orm, --file, --operation, --json) |

AI Integration

| Command | Purpose | |---------|---------| | srcpilot search-hook | Enriches Grep/Glob/Read tool results with graph context (used as a Claude Code hook) | | srcpilot generate-skills | Writes per-community SKILL.md files to .srcpilot/skills/ for AI tool context injection |

Setup and Multi-Repo

| Command | Purpose | |---------|---------| | srcpilot setup | Interactive AI tool installer (--agent, --all, -g, --hooks, --copy) | | srcpilot group create <name> | Create a named multi-repo group | | srcpilot group add <name> | Add the current repo to a group | | srcpilot group remove <name> | Remove the current repo from a group | | srcpilot group list | List all groups | | srcpilot group show <name> | Show members of a group | | srcpilot group query <name> <symbol> | Cross-repo symbol search across all group members |

Judgment Commands in Depth

why, next, ambiguities, change-impact, and implementations form the judgment layer. They combine graph structure, file metrics, role classification, and optional explicit evidence to produce deterministic ranked guidance.

srcpilot why <query> Ranks likely root nodes, likely owners, and ambiguity traps. With --log, it incorporates compile-frontier evidence and subsystem dominance. Returns ambiguity cluster summaries and compile subsystem summaries, not just file lists.

srcpilot next <query> Ranks the best files to open first. Uses workspace ownership and provenance so cache, vendor, and generated paths are demoted. With --log, it applies compile-frontier collapse potential to select the highest-leverage starting point.

srcpilot ambiguities [query] Flags duplicate names, runtime/test splits, and other collision risks detected in the index.

srcpilot implementations <symbol> Groups explicit and graph-adjacent competing implementations of the same concept.

srcpilot change-impact <symbol> Returns direct dependents, likely behavioral dependents, suggested test files, and a risk level for touching that symbol.

All judgment commands accept evidence flags:

srcpilot why PaymentProvider
srcpilot next "fix payment flow"
srcpilot next --log /tmp/build.log "fix compile errors"
srcpilot why --log /tmp/build.log "fix current compile errors"
srcpilot why --test-log /tmp/jest.log "why is checkout failing"
srcpilot next --stack /tmp/stack.txt --diff /tmp/changes.diff "what to open first"
npm run build 2>&1 | srcpilot why --log - "why is this failing"
srcpilot ambiguities PaymentProvider
srcpilot impact PaymentProvider --depth decision --why

Evidence flags: --log (compile/build log), --test-log (test failure output), --stack (stack trace), --diff (git diff).

Graph Intelligence Commands in Depth

srcpilot routes Queries the indexed HTTP route map. Filter by method, path prefix, or framework. Returns handler location, middleware chain, and framework detection.

srcpilot routes --method POST --framework express
srcpilot routes --path /api/payments --json

srcpilot flows Returns BFS execution paths from detected entry points to terminal nodes. Use --min-length to filter trivial flows and --depth to control traversal depth.

srcpilot flows --depth 6 --min-length 3 --limit 20

srcpilot communities Returns the module clusters produced by label-propagation over the import graph. Each community has a label derived from its dominant files and lists every member.

srcpilot communities --json

srcpilot rename <old> <new> Produces a confidence-scored plan for renaming a symbol across all files. Dry-run mode shows every proposed change without writing. Execute mode applies all high-confidence changes. --include-uncertain extends the plan to lower-confidence matches.

srcpilot rename PaymentProvider PaymentService --dry-run
srcpilot rename PaymentProvider PaymentService --execute

srcpilot shape-check Compares the return shapes of handlers with the property accesses made by their consumers. Reports mismatches where a consumer accesses a field the handler does not return.

srcpilot db-queries Lists every ORM call and raw SQL statement found in the index with its location, model, operation, and ORM type. Filter by any combination of --model, --orm, --file, and --operation.

srcpilot db-queries --orm prisma --operation findMany
srcpilot db-queries --model User --json

srcpilot trace <file> Traverses the import graph from a starting file. Direction deps follows what the file imports; direction dependents follows what imports the file. Cross-repo boundaries are annotated when the dep name matches a group member's package.json name.

srcpilot trace src/payments/index.ts --direction dependents --depth 4

MCP Server

srcpilot serve starts an MCP server over stdio. Add it to your MCP client configuration:

{
  "mcpServers": {
    "srcpilot": {
      "command": "npx",
      "args": ["-y", "srcpilot", "serve"]
    }
  }
}

The MCP server exposes all navigation and judgment capabilities as tools:

| Tool | Purpose | |------|---------| | find_symbol | Find symbols by name | | find_usages | Find importers of a symbol | | file_overview | List symbols in a file | | related_files | Files connected by import or graph relation | | navigate | Multi-channel search | | why | Ranked root cause and owner guidance | | next | Ranked next-file guidance | | ambiguities | Duplicate-name and collision risks | | implementations | Competing implementations | | change_impact | Dependents, suggested tests, risk level | | context_budget | Files ranked by centrality | | api_surface | Exported symbols | | dead_code | Unused exports | | circular_deps | Circular import chains | | map | Project overview from the index | | detect_changes | Files changed since last index | | route_map | Indexed HTTP routes with filter support | | execution_flows | BFS execution flow traces | | communities | Module clusters | | rename_plan | Multi-file rename plan with confidence scoring | | shape_check | API shape mismatch detection | | db_queries | ORM/SQL query lookup by model, ORM, file, or operation | | group_query | Cross-repo symbol search across a named group |

AI Integration

Search Hook

srcpilot setup --hooks installs a Claude Code hook that fires srcpilot search-hook before Read, Grep, and Glob tool calls. The hook injects graph context — importers, symbol definitions, and route connections — directly into the tool result, so the AI sees structural context alongside file content without any extra prompting.

Module Skills

srcpilot generate-skills writes a SKILL.md file for each module community detected in the index. These files live at .srcpilot/skills/<community-label>/SKILL.md and describe which symbols, files, and responsibilities belong to each cluster.

srcpilot setup links these skill files into the AI tool's rules directory so the AI knows which symbols belong to which module cluster before it opens a single file.

Multi-Repo Groups

srcpilot maintains a global group registry at ~/.srcpilot/registry.json. Individual repos opt in by adding .srcpilot/group.yaml identifying which group they belong to.

Once repos are grouped, cross-repo search works from any member:

srcpilot group create payments-platform
srcpilot group add payments-platform
srcpilot group query payments-platform PaymentProvider

srcpilot group query searches all member repos for a symbol and returns results with their repo of origin. srcpilot trace annotates cross-repo boundaries when an import name matches a group member's package.json name, letting you follow a dependency chain across repository boundaries.

The MCP group_query tool exposes the same capability to MCP clients.

Setup and Supported Agents

srcpilot setup installs srcpilot's guidance files into your AI tool's rules directory. It detects likely local agents and presents an interactive menu, or you can drive it non-interactively:

# Interactive
npx -y srcpilot setup

# Install to specific agents
npx -y srcpilot setup --agent codex --agent claude-code

# Install globally for every supported agent without prompts
npx -y srcpilot setup --all -g -y

# Install Claude Code hooks (search augmentation)
npx -y srcpilot setup --hooks

# List all supported agent IDs
npx -y srcpilot setup --list-agents

Flags: --agent <id> targets a specific agent, --all targets every supported agent, -g installs globally, --copy uses file copies instead of symlinks, --hooks installs search-augmentation hooks.

Supported targets include Codex, Claude Code, Cursor, Gemini CLI, GitHub Copilot, OpenCode, OpenHands, Roo Code, Windsurf, Continue, Cline, Kiro CLI, and the full set registered in the installer registry.

Configuration

srcpilot reads .srcpilot/config.json in the project root.

{
  "version": 1,
  "exclude": ["dist/**"],
  "maxFiles": 50000,
  "roleOverrides": {
    "packages/editor/**": "editor",
    "packages/runtime/**": "runtime"
  },
  "roleExcludes": ["packages/editor/generated/**"],
  "workspaceRoots": ["packages/**", "apps/**"]
}

Fields:

• exclude — glob patterns to skip during indexing
• maxFiles — index file cap (0 means unlimited; default applies a conservative limit)
• roleOverrides — map glob patterns to built-in roles (runtime, test, editor, generated, vendor, mock, script)
• roleExcludes — glob patterns excluded from role override matching
• workspaceRoots — package boundaries for monorepos, used to sharpen ownership ranking

Environment variables:

• SRCPILOT_PROJECT_ROOT — override project root detection
• SRCPILOT_MAX_FILES — override the index file limit
• SRCPILOT_PARSER_HOME — override the local parser cache directory

For large monorepos, raise or remove the file limit at index time:

npx -y srcpilot init --max-files 0
npx -y srcpilot index --max-files 50000 /path/to/repo

Staleness Detection

After srcpilot index completes, the current HEAD commit hash is stored in the index. Every subsequent query compares live HEAD to the stored hash. If the repo has advanced past the indexed commit, srcpilot prints a staleness warning so you know to re-index before relying on the results. Pass --no-stale-check to suppress this warning when you intentionally query a stale index.

Background Daemon

srcpilot index --auto starts a single global background daemon that watches your project for file changes and incrementally re-indexes them. The daemon detaches from the terminal — no shell needs to stay open.

# Start watching the current project (daemon starts automatically)
srcpilot index --auto

# Watch multiple projects — they share one daemon process
cd ~/projects/api && srcpilot index --auto
cd ~/projects/web && srcpilot index --auto

# Check daemon status and watched projects
srcpilot index --status

# Remove a project from the watch list
srcpilot index --stop

# Stop the daemon entirely
srcpilot index --stop --all

The daemon is lightweight and designed for multiple concurrent projects:

• Single process — one global daemon at ~/.srcpilot/ manages all watched projects, regardless of how many repos are registered
• Kernel-level watching — uses fs.watch (inotify on Linux, FSEvents on macOS) instead of polling
• Incremental updates — only changed files are re-parsed via indexSingleFile, typically completing in under 100ms
• Debounced — rapid saves are batched (1s window) to avoid redundant work
• Periodic full scan — every 10 minutes, a full scan catches file deletions and any events the watcher missed
• Self-healing — stale PID files are cleaned automatically; the daemon exits when no projects remain

State files live under ~/.srcpilot/:

| File | Purpose | |------|---------| | daemon.pid | PID of the running daemon | | daemon.log | Rolling log (truncated at 2 MB) | | watched.json | List of registered project roots |

Auto-Update

The daemon checks npm for a newer version of srcpilot every hour. If an update is found, it installs the new version globally and restarts itself. All watched projects remain registered across restarts — no manual re-registration needed.

The update check is non-blocking: if npm is unreachable or the install fails, the daemon continues running the current version and retries on the next cycle.

Supported Languages

TypeScript, TSX, JavaScript, JSX, Python, Go, Rust, Java, Kotlin, Ruby, C#, PHP, Swift, C, C++, and Bash.

Language grammars are not bundled in the core package. On first init or index, srcpilot detects the languages present in the repo, downloads only the grammars it needs, and caches them locally for subsequent runs. Progress is shown in the terminal:

Preparing parser support for c_sharp
Installing parser support: tree-sitter-c-sharp
Parser support ready: tree-sitter-c-sharp

Output Modes

Judgment commands support four depth modes, set with --depth:

• brief — top 3 results, concise rationale, no snippets
• decision — top 5 results, short snippets, tuned for "what should I open first?"
• full — top 10 results with extended context and ambiguity sections
• patch-context — patch-safety output with longer snippets and richer impact context

All commands accept --json for machine-readable output. JSON output includes ranking metadata:

• analysis_mode, intent, ecosystem
• matched_evidence, collapse_potential, causal_degree
• support_eligible, subsystem_error_mass, owner_confidence

Use --explain-ranking to expose score rationale in JSON output.

Global Flags

| Flag | Purpose | |------|---------| | --json | Machine-readable output on all commands | | --project <path> | Override project root | | --depth <mode> | brief / decision / full / patch-context | | --limit <n> | Cap results | | --include-role <csv> | Filter output to specific file roles | | --exclude-role <csv> | Drop specific file roles from output | | --log <path\|-> | Compile/build log evidence for why and next | | --test-log <path\|-> | Test failure evidence for why and next | | --stack <path\|-> | Stack trace evidence for why and next | | --diff <path\|-> | Git diff evidence for why and next | | --why | Include inline rationale on ranked results | | --explain-ranking | Expose score metadata in JSON output | | --max-files <n> | Override index file cap for init and index | | --no-stale-check | Suppress staleness warning | | index --auto | Start background daemon watching the current project | | index --stop | Remove the current project from the daemon watch list | | index --stop --all | Kill the global daemon entirely | | index --status | Show daemon PID and all watched projects | | --version / -v | Print version | | --help / -h | Print help |

How It Works

1. Tree-sitter parses source files into ASTs for each supported language.
2. A multi-pass extractor pulls symbols, imports, call edges, HTTP routes, ORM queries, execution flows, and class hierarchy from the ASTs.
3. Everything is written to .srcpilot/db.sqlite using FTS5 for text search and dedicated tables for the graph, metrics, routes, flows, and communities.
4. CLI and MCP tools query the saved index directly — no parsing on query.
5. Judgment commands combine evidence, ownership, graph centrality, call-graph confidence, ambiguity clusters, and role-aware policies to produce deterministic ranked output.

Why It Stays Lightweight

srcpilot is designed to remain local, fast, and auditable:

• SQLite-backed — no external graph database, no network calls for queries
• No embeddings — symbol matching is lexical and graph-structural
• No vector store — all indices are standard SQL with FTS5
• No model in the ranking loop — every score is a deterministic function of the graph
• Small core install — language grammars are fetched on demand per repo and cached locally
• Incremental reindex — srcpilot reindex <file> updates a single file without rebuilding the whole index
• Background daemon — srcpilot index --auto watches for changes with a single shared process across all projects
• Auto-update — the daemon checks npm hourly and self-updates without manual intervention
• Snippets are read only for final result rendering, not during whole-repo scoring

License

MIT