Search BrigadeStack

Search BrigadeStack pages and docs.

BrigadeStack
Menu
Docs menu

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 setup installs brigade-code-graph and brigade-code-graph-mcp as 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_delta summary on the receipt.

  • Runs get a graph brief

    brigadestack run attaches a bounded context pack to the worker prompt when the index exists, and records the attached bytes in run.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-graph skips 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)
Result 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
Result 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...
Result 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",...
Result 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.

Index time

baseline 0.74 s
engine 0.12 s

Peak memory

baseline 389 MB
engine 14 MB
tool-surface/README.md

Incremental 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.

One-file change

before 2 m 52 s
after 2.5 s

Full-index peak memory

before 397 MB
after 136 MB
implementation-notes.md

Read-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

  • search
  • outline
  • callers
  • callees
  • impact
  • context
  • stats
  • doctor
  • file_neighbors
  • dead_code
  • cycles
  • affected
  • explain
  • diff
  • repos

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 --depth to follow edges further.
context
Rank entry points and related files for a task. Add --json, or --markdown for 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, or jsonl, 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 for STALE, 2 for NEEDS-MIGRATION or a missing database.