[ CODE GRAPH · v0.1.0 ]
The map of your code, before the agent edits it.
GraphTrail indexes your repo into a small SQLite graph of symbols, imports, and call edges, then answers structural questions, callers, callees, impact, and context, over a CLI and a read-only MCP server. Python, TS/JS, Rust, and Go. No daemon, no network.
Le plan: the map every station works from.
[ 01 · FLOW ]
Index · once, then incremental
- graphtrail init points at a repo
- tree-sitter parses each file in one pass
- symbols, imports, and call edges extracted per language
- written to a small local SQLite graph
- graphtrail sync is incremental, a no-op when nothing changed
Query · before you edit
- search symbols by name or text
- callers and callees of any symbol
- impact, the blast radius of a change
- context, a graph pack for a term or symbol
- over the CLI or the read-only MCP server
GraphTrail stays a sidecar. It owns symbols, imports, call edges, and graph context, and nothing else. Code Search keeps semantic chunks and embeddings, MiseLedger owns evidence archives, and Brigade owns workflow and guardrails.
[ 02 · MCP SERVER ]
graphtrail-mcp is a read-only MCP server (newline-delimited JSON-RPC over stdio). It exposes the query commands as tools, search, callers, callees, impact, context, file_neighbors, repos, and stats, and opens the database read-only, so it can never mutate the graph. It is multi-repo: one running server answers for any indexed repository, and the database is opened lazily per call.
Register it with any MCP client (Claude Code shown):
{
"mcpServers": {
"graphtrail": {
"command": "/abs/path/to/graphtrail-mcp",
"args": ["--db", "/abs/path/to/repo/.graphtrail/graphtrail.db"]
}
}
} [ 03 · GUARANTEES ]
AST, not regex
Symbols, imports, and call edges come from the tree-sitter AST in one pass per file, behind a per-language provider. Call edges resolve by name, same-file first, then a capped cross-file match.
Four languages today
Python, TypeScript/JavaScript, Rust, and Go, each a LangSpec provider. The graph shape is identical across all of them.
Read-only after indexing
Once the graph is built, GraphTrail only reads. It installs no hooks, starts no daemon, and makes no network calls.
Read-only MCP, multi-repo
graphtrail-mcp opens the database read-only and answers for any indexed repo from one process. It starts even before a default database exists.
Brigade adapter built in
context --markdown renders a graph context pack as a Brigade-friendly markdown document, droppable straight into a handoff evidence section.
Optional Code Search + MiseLedger
Cargo features blend Code Search embedding hits with graph centrality, and surface MiseLedger evidence mentioning a symbol. The default binary stays free of network and cross-tool dependencies.
[ 04 · COMMANDS ]
| Command | What it does |
|---|---|
| graphtrail init <repo> | Create the graph database and index every supported file. |
| graphtrail sync <repo> | Incremental re-index, a no-op when nothing changed. Add --force to rebuild every file. |
| graphtrail search <query> | Full-text search over symbols. Add --path to scope to a directory. |
| graphtrail callers <symbol> | Every symbol that calls this one. |
| graphtrail callees <symbol> | Every symbol this one calls. |
| graphtrail impact <symbol> | The blast radius: what a change here can reach. |
| graphtrail context <query> | A graph context pack for a term or symbol. Add --json, or --markdown for a Brigade handoff. |
| graphtrail neighbors <path> | A file's structural neighborhood: its symbols, import links, and call-connected files. |
| graphtrail stats | Counts of files, symbols, edges, and imports, plus sync freshness. Add --json. |
Index a repo, then drop a graph context pack straight into a Brigade handoff:
[ 06 · LINKS ]
[ MORE FROM ESCOFFIER LABS ]
Local-first tools for AI coding agents
One kitchen, one brigade. Each tool does one job well, and they share one reviewed source of memory, config, and receipts.