README
¶
codegrapher
A code intelligence tool that builds and queries a SQLite knowledge graph of every symbol, edge, and file in a codebase. Written in Go; single static binary, no runtime dependencies.
Website: https://codegrapher.dev
Our approach to development
We build with our own tooling:
- SpecScore — specify requirements as
SpecScore.mdartifacts - SpecStudio — author & manage specs across their lifecycle
- inGitDB — store structured data in Git where applicable
- DALgo — data access layer for Go
- cover100.dev — drive toward 100% test coverage
- DataTug — query & explore data
Usage
codegrapher init [path] Initialize .codegraph/ and build the initial index
codegrapher uninit [path] Remove .codegraph/ from a project
codegrapher index [path] Full re-index
codegrapher sync [path] Incremental re-index (`--init` initializes when missing)
codegrapher status [path] Index stats (--json)
codegrapher query <search> Symbol search (-l limit, -k kind, --brief, --json)
codegrapher node <symbol> Symbol metadata/source/relations (--source[=footer|inline], --relations, --file, --line, --json)
codegrapher path <from> <to> One bounded static call path (--max-hops, --max-nodes, --max-edges, --source[=footer|inline], --json)
codegrapher stacktrace [file] Map runtime frames to symbols (--max-bytes, --max-frames, --revision, --source[=footer|inline], --json)
codegrapher files Indexed file tree (--json)
codegrapher callers <symbol> What calls this symbol (--json)
codegrapher callees <symbol> What this symbol calls (--json)
codegrapher impact <symbol> Blast-radius analysis (--json)
codegrapher affected [files] Test files affected by changed sources (--json)
codegrapher watch [path] Compatibility foreground watcher (--verbose)
codegrapher serve [path] Composable foreground server (--watch, --api, --mcp)
codegrapher daemon start Background freshness owner
codegrapher daemon status Daemon lifecycle/freshness health (--json)
codegrapher daemon stop Gracefully stop background owner
codegrapher export [path] Export index as INGR snapshot files
codegrapher import [path] Import an INGR snapshot into the local store
codegrapher unlock [path] Remove a stale lock file
codegrapher version Print version
Trace a precise code route
Use path when the entry and target symbols are known but the intermediate
calls are not. It returns one deterministic shortest directed calls path;
the default is signatures and locations, not source bodies.
codegrapher path main NewRootCmd --max-hops 8 --max-nodes 1000 --max-edges 5000
codegrapher path "function:exact-start-id" "function:exact-target-id" --source=footer
Each hop includes edge kind, call-site line/column, and extraction provenance.
Ambiguous endpoints produce candidates and require an exact ID. --source is
Markdown-only: footer writes compact JSON metadata followed by deduplicated,
raw language fences; inline is also valid with --format json.
The traversal is explicitly bounded by hops, visited nodes, and inspected
edges; a truncated result says so rather than silently broadening the search.
Read a runtime stack without file-chunk hunting
stacktrace maps file-and-line runtime frames to the smallest enclosing
indexed callable. It accepts a trace file, -, or stdin:
codegrapher stacktrace panic.txt
pbpaste | codegrapher stacktrace --source=footer
codegrapher stacktrace trace.txt --source=inline --format json
codegrapher stacktrace prod-panic.txt --revision "<deployed-git-sha>"
Go, V8 JavaScript/TypeScript, Python, JVM, .NET, Rust, and generic
file:line[:column] frames are recognized. Stack order and unmatched/external
frames are preserved. A stack is runtime evidence, so adjacent frames do not
need a static graph edge. Source is deduplicated for recursion and repeated
frames, and only returned after the indexed file hash is verified.
Input bytes and mapped-frame count are bounded. A runtime function name that
contradicts the symbol containing its file:line is reported as mismatch,
and a shifted line with a matching name in the same file is reported as
stale; neither silently returns source.
After refreshing, each command takes the index's short cross-process read lock
while it resolves relationships and verifies source. If indexing is active it
returns a busy/retry error rather than combining an old graph with new code.
Snapshot / viewer
codegrapher export writes the index as INGR snapshot files
that can be committed to the repo. codegrapher import seeds the store from a
committed snapshot, turning cold-start indexing into seconds. Committed snapshots
also power the codegrapher.dev browser viewer for symbol search and callers/callees
navigation without a local index.
Language support
Go and TypeScript/JavaScript. Go files are parsed by the standard library
go/parser; TypeScript/JavaScript are parsed via
gotreesitter (pure Go, no CGO).
go.mod files are also indexed, producing module and dependency nodes with
require/replace/exclude relationships. package.json files are likewise
indexed, producing module and dependency nodes across dependencies,
devDependencies, peerDependencies, and optionalDependencies, stored in a
dedicated node scope merged into JS/TS queries.
Build
CGO_ENABLED=0 go build ./cmd/codegrapher
No CGO, no runtime dependencies. Cross-compiles to any Go target.
License
Apache-2.0. See LICENSE and NOTICE for attribution to the original codegraph (MIT, Colby McHenry) and the gotreesitter fork (MIT, Oscar Villavicencio) used for TypeScript/JavaScript parsing.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package agentplugin embeds CodeGrapher's publishable Agent Skills bundle.
|
Package agentplugin embeds CodeGrapher's publishable Agent Skills bundle. |
|
Package browserapi exposes one initialized CodeGrapher repository through a versioned, authenticated, read-only HTTP API for browser consumers.
|
Package browserapi exposes one initialized CodeGrapher repository through a versioned, authenticated, read-only HTTP API for browser consumers. |
|
cmd
|
|
|
codegrapher
command
Command codegrapher is the drop-in Go replacement for the original colbymchenry/codegraph TypeScript CLI.
|
Command codegrapher is the drop-in Go replacement for the original colbymchenry/codegraph TypeScript CLI. |
|
Package coverage is the single home for Go line-coverage attribution in codegrapher: it turns a `go test -coverprofile` profile into per-file and per-function coverage records, and defines the INGR recordset format those records are exported/uploaded/served in.
|
Package coverage is the single home for Go line-coverage attribution in codegrapher: it turns a `go test -coverprofile` profile into per-file and per-function coverage records, and defines the INGR recordset format those records are exported/uploaded/served in. |
|
Package daemon owns CodeGrapher's single-user background freshness process.
|
Package daemon owns CodeGrapher's single-user background freshness process. |
|
Package freshness owns one repository's index, native watcher, startup reconciliation, generation barrier, health, and joined shutdown.
|
Package freshness owns one repository's index, native watcher, startup reconciliation, generation barrier, health, and joined shutdown. |
|
Package gomod parses go.mod files into a typed, line-annotated structure.
|
Package gomod parses go.mod files into a typed, line-annotated structure. |
|
Package indexer orchestrates building and maintaining a codegraph index: directory management, file scanning, full indexing (Init), incremental sync, git-hook installation, and git-worktree awareness.
|
Package indexer orchestrates building and maintaining a codegraph index: directory management, file scanning, full indexing (Init), incremental sync, git-hook installation, and git-worktree awareness. |
|
internal
|
|
|
cli
Package cli provides the Cobra command tree for the codegraph binary.
|
Package cli provides the Cobra command tree for the codegraph binary. |
|
extract
Package extract provides AST-based symbol extraction for Go and TypeScript/JavaScript files.
|
Package extract provides AST-based symbol extraction for Go and TypeScript/JavaScript files. |
|
paritytest
Package paritytest compares codegrapher output against golden outputs captured from the original codegraph CLI (testdata/golden), implementing the normalization rules documented in tools/parity/README.md:
|
Package paritytest compares codegrapher output against golden outputs captured from the original codegraph CLI (testdata/golden), implementing the normalization rules documented in tools/parity/README.md: |
|
tsparse
Package tsparse wraps the gotreesitter pure-Go tree-sitter runtime, exposing a thin Parser type and a Node type that the rest of the codebase can walk without importing gotreesitter directly.
|
Package tsparse wraps the gotreesitter pure-Go tree-sitter runtime, exposing a thin Parser type and a Node type that the rest of the codebase can walk without importing gotreesitter directly. |
|
Package lock implements a cross-process file lock using an exclusive PID file, ported from FileLock in src/utils.ts of github.com/colbymchenry/codegraph (MIT).
|
Package lock implements a cross-process file lock using an exclusive PID file, ported from FileLock in src/utils.ts of github.com/colbymchenry/codegraph (MIT). |
|
Package mcp implements the MCP (Model Context Protocol) server for codegrapher — a behavior-parity port of upstream codegraph's MCP surface (src/mcp/tools.ts + src/context/index.ts), served over stdio.
|
Package mcp implements the MCP (Model Context Protocol) server for codegrapher — a behavior-parity port of upstream codegraph's MCP surface (src/mcp/tools.ts + src/context/index.ts), served over stdio. |
|
Package model defines the core knowledge-graph types shared by every codegrapher package: nodes, edges, file records, and their kind enums.
|
Package model defines the core knowledge-graph types shared by every codegrapher package: nodes, edges, file records, and their kind enums. |
|
Package pkgjson parses package.json files into a typed structure.
|
Package pkgjson parses package.json files into a typed structure. |
|
Package query implements the QUERY layer: symbol search, graph traversal (callers/callees/impact), and index status/files verbs.
|
Package query implements the QUERY layer: symbol search, graph traversal (callers/callees/impact), and index status/files verbs. |
|
Package resolve turns the store's unresolved_refs table into edges.
|
Package resolve turns the store's unresolved_refs table into edges. |
|
Package scope identifies the (language, toolchain-version) partition a source file belongs to.
|
Package scope identifies the (language, toolchain-version) partition a source file belongs to. |
|
Package snapshot exports and imports the codegrapher index as INGR files.
|
Package snapshot exports and imports the codegrapher index as INGR files. |
|
Package specdoc is a thin codegrapher-owned adapter over the specscore-cli artifact parsers (github.com/specscore/specscore-cli).
|
Package specdoc is a thin codegrapher-owned adapter over the specscore-cli artifact parsers (github.com/specscore/specscore-cli). |
|
Package store — FTS5 search methods.
|
Package store — FTS5 search methods. |
|
tools
|
|
|
fixtures/sqlite-small
command
Command sqlite-small generates the committed binary fixture testdata/fixtures/sqlite-small/app.db and its self-goldens under testdata/golden/sqlite-small/.
|
Command sqlite-small generates the committed binary fixture testdata/fixtures/sqlite-small/app.db and its self-goldens under testdata/golden/sqlite-small/. |
|
Package trace builds and queries the CodeGrapher projection of SpecScore trace records.
|
Package trace builds and queries the CodeGrapher projection of SpecScore trace records. |
|
Package watch provides file-system watching with debounced sync callbacks.
|
Package watch provides file-system watching with debounced sync callbacks. |