codegrapher

module

v0.2.2 Latest Latest Go to latest Published: Sep 1, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/specscore/codegrapher

Links

Open Source Insights

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.md artifacts
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 since last index
codegrapher status [path]    Index stats                         (--json)
codegrapher query <search>   Symbol search                       (-l limit, -k kind, --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 serve            MCP server (stdio)
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

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 ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
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.
coverage 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.
gomod Package gomod parses go.mod files into a typed, line-annotated structure.	Package gomod parses go.mod files into a typed, line-annotated structure.
indexer 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.
lock 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).
mcp 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.
model 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.
pkgjson Package pkgjson parses package.json files into a typed structure.	Package pkgjson parses package.json files into a typed structure.
query 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.
resolve Package resolve turns the store's unresolved_refs table into edges.	Package resolve turns the store's unresolved_refs table into edges.
scope 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.
snapshot Package snapshot exports and imports the codegrapher index as INGR files.	Package snapshot exports and imports the codegrapher index as INGR files.
specdoc 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).
store 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/.
watch Package watch provides file-system watching with debounced sync callbacks.	Package watch provides file-system watching with debounced sync callbacks.