Docs / Built-in tools
See what a change touches before an agent edits it.
A local code graph in Rust, parsed with tree-sitter and stored in SQLite, queried over the CLI or a read-only MCP server.
Runs on its own.
Setup installs the engine. Verify and run use it without being asked.
-
Setup installs both binaries
brigadestack setupinstallsbrigade-code-graphandbrigade-code-graph-mcpas default managed components, checked against a verified release manifest. No Rust toolchain needed. -
Verify records the graph delta
Each verify run syncs before your commands and after, diffs the two, and stores a
code_graph_deltasummary on the receipt. -
Runs get a graph brief
brigadestack runattaches a bounded context pack to the worker prompt when the index exists, and records the attached bytes inrun.json. -
Fails open
A missing engine, a failed sync or a bad snapshot is written to the receipt as a status. It never fails the run, and
--no-code-graphskips the step.
Still manual: sync once per repo, because run briefs wait for the index. Verify waits 10 seconds for its sync by default (--code-graph-timeout), so a large first index can record sync_timed_out instead of a delta. There is no watch, because brigadestack code does not expose the engine's watch command. You register the MCP server with your client yourself.
Ask before you edit.
Four questions to put to the graph first. Each one is a real command with its real output.
Impact
“What breaks if I change retry?”
Callers and tests that reach the symbol, one hop by default. Add --depth to follow edges further.
brigadestack code sync .indexed files=5 symbols=7 calls=7 imports=6 deleted=0 db=./.brigade/code-graph/code-graph.dbbrigadestack code impact retryfetch_page --calls@5 hops=1--> retry (app/fetch.py -> app/retry.py)retry --calls@13 hops=1--> backoff (app/retry.py -> app/retry.py)sync_all --calls@6 hops=1--> retry (app/sync.py -> app/retry.py)test_retry_returns_value --calls@5 hops=1--> retry (tests/test_retry.py -> app/retry.py) 2 callers, 1 test, 1 callee, all at hop 1 Affected tests
“Which tests should I run?”
Tests statically attributed to the changed files. Treat the list as a lower bound.
brigadestack code affected app/retry.pychanged: 1 known, 0 missing (depth 3)note: tests statically attributed through incoming call edges; a lower bound, not coverage. Absence here does not mean untested (fixtures, dynamic dispatch, and harness-driven tests are invisible to call edges).affected tests: 2- tests/test_retry.py hops=1 via test_retry_returns_value- tests/test_sync.py hops=2 via test_sync_all_emptyimpacted files: 2- app/fetch.py hops=1- app/sync.py hops=1 2 tests, 2 impacted files Context pack
“What should the agent read first?”
Ranked entry points, callers, callees and related files for a task. Add --json, or --markdown for a handoff.
brigadestack code context "retry backoff"# Contexttask: retry backoff## Entry Points- function `backoff` at app/retry.py:4-5- function `retry` at app/retry.py:8-14- function `test_retry_returns_value` at tests/test_retry.py:4-5## Callers- `retry` calls `backoff` at app/retry.py:13 -> app/retry.py- `fetch_page` calls `retry` at app/fetch.py:5 -> app/retry.py...## Related Files- app/fetch.py- app/retry.py... 3 entry points, 4 related files MCP
“Can my agent ask this itself?”
The same queries over stdio, read-only. Lines marked > go to the server after the initialize handshake. Lines marked < come back. Register the server with your client yourself.
brigade-code-graph-mcp --db .brigade/code-graph/code-graph.db> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"impact","arguments":{"symbol":"retry"}}}< result.content[0].text:"ambiguous": false,"candidates": [ ... ],"edges": ["hops": 1,"kind": "calls","line": 5,"source": "fetch_page","source_file": "app/fetch.py","target": "retry",... 1 candidate, 4 edges, all at hop 1 Measured.
Two benchmarks, with their conditions. Both are the project's own measurements. Bars are drawn to scale within each pair.
Setup cost vs a baseline
Corpus: the engine's own repository at the time, 84 files and 712 symbols. On 12 agent questions it hit 11 and the baseline hit 9. The source does not name the baseline or record the hardware.
tool-surface/README.mdIncremental sync at scale
Corpus: a 16,686-file TypeScript repo, release build, before and after the incremental-sync rewrite. Full-index time was 19.8 s before and 21.4 s after.
implementation-notes.mdRead-only MCP server.
brigade-code-graph-mcp speaks newline-delimited JSON-RPC 2.0 over stdio. Query connections open the database read-only, and one server answers for any indexed repo through a repo or db argument.
The 15 tools
searchoutlinecallerscalleesimpactcontextstatsdoctorfile_neighborsdead_codecyclesaffectedexplaindiffrepos
Register with an MCP client (Claude Code shown)
{
"mcpServers": {
"brigade-code-graph": {
"command": "/abs/path/to/brigade-code-graph-mcp",
"args": ["--db", "/abs/path/to/repo/.brigade/code-graph/code-graph.db"]
}
}
} Without refresh the query tools never write the graph. A query that sets refresh: true starts an incremental index write and waits up to 10 seconds before it reads.
Where it fits.
The graph owns one slice: symbols, imports, call edges and graph context.
Next to grep
grep finds every line a name appears on. The graph answers who calls a function, from tree-sitter call edges.
Next to Code Search
Code Search keeps semantic chunks and embeddings and ranks by similarity. The graph adds what a change can reach, and the two compose.
Next to a language server
A language server is a stateful daemon for one project. The graph is one SQLite file per repo that an agent can query read-only over MCP, with no daemon and no network call in the default build.
Inside BrigadeStack
Receipts, memory, publishing and scheduling live in the workflow and Evidence layers. The graph supplies symbols, imports, call edges and context to them, and never edits your code.
Command reference.
Every verb runs as brigadestack code <verb>.
sync- Index or refresh the repo's code graph. This is also how the first graph gets built.
search- Search indexed symbols by name.
outline- One file's symbols in source order.
callers- Every symbol that calls this one.
callees- Every symbol this one calls.
impact- The blast radius of changing a symbol. Add
--depthto follow edges further. context- Rank entry points and related files for a task. Add
--json, or--markdownfor a handoff. neighbors- A file's incoming and outgoing graph neighbors.
affected- Tests statically attributed to changed files. Treat it as a lower bound on what to run.
dead-code- Callables with no incoming call edges. Treat them as candidates.
cycles- File-level dependency cycles.
explain- How call edges between two symbols resolved.
diff- Diff two indexed graph databases.
export- Export the graph as
dot,graphml, orjsonl, or as the Center JSON contract with--json. evaluate- Dry-run extraction: print what a sync would store, writing nothing.
stats- Counts of files, symbols, edges, and imports, plus sync metadata.
doctor- Check graph health. Exits 0 for
FRESH, 1 forSTALE, 2 forNEEDS-MIGRATIONor a missing database.