CodeGraph

What It Does

CodeGraph builds a per-project knowledge graph of your codebase (symbols, call edges, imports, files) in a local SQLite database with FTS5 search, and exposes it to AI coding agents over MCP so they answer structural questions in one tool call instead of crawling files with grep and Read. A Rust kernel parses 20 languages in compiled code with the remaining 15 or so on a portable engine, a file watcher keeps the index current as code changes, and a CLI (codegraph init, explore, callers, impact, affected) mirrors every MCP tool. The installer wires the MCP server into 9 agents: Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity, Kiro, and GitHub Copilot across three surfaces. The user is any developer whose agent spends its budget re-deriving codebase structure, and the product ships as an npm package, a self-contained bundle, or a library API. It is the largest node of the code-intelligence lane the scanner tracks (69,796 stars, ahead of codebase-memory-mcp at 42K and K-Dense scientific-agent-skills at 43K).

The Good

The graph is real, and the query results are correct on live code. On a synthetic TypeScript and Python fixture, codegraph explore "how does handlePostUsers reach UserRepo.save" returned a numbered chain with exact locations: 1. handlePostUsers (src/route.ts:4) ↓ calls 2. registerUser (src/service.ts:3) ↓ calls 3. save (src/db.ts:5), followed by verbatim source. The same held on codegraph's own repo: indexing 787 files produced 16,905 nodes and 64,099 edges in 30 seconds, and an explore query about the MCP server's tool registration answered in 3 seconds with 76 symbols across 4 files plus a blast-radius section naming which tests cover the callers. callers upsertCodeGraphMcpServer correctly resolved to writeHermesConfig. Traversals are not decorative: they name the right files and lines.

The Hermes Agent support is first-class, correct down to a detail most vendors miss. The 356-line Hermes target (the second largest of 14 installer targets) writes both mcp_servers.codegraph and an mcp-codegraph entry into platform_toolsets.cli, with an in-code comment explaining why: Hermes CLI profiles often filter tools to an explicit toolset list, so an MCP server can be connected but invisible. Verified live in an isolated HERMES_HOME: install created both entries, a second install against a config that already held model: and another MCP server preserved everything (upsert, not clobber), and uninstall removed only the codegraph entries. The target even handles PyYAML's flat list serialization (regression test references issue #456).

Supply-chain posture is above everything else in this tier. Releases are built only by a public GitHub Actions workflow using npm OIDC trusted publishing (no long-lived npm tokens), carry npm provenance attestations and SLSA v1.0 Build Level 2 artifact attestations, and publish SHA256SUMS. GearScope downloaded the v1.6.0 darwin-arm64 bundle and verified the SHA256 against the sums file: byte-exact match (1c730335...ad480). The bundle runs on a vendored Node runtime, verified by invoking the CLI with a PATH containing no node at all.

4,240 committed tests, and they pass. On a bare clone with dependencies installed, 3,950 of 4,240 tests pass in 130 seconds; the 84 failures are all CLI and MCP integration tests that spawn dist/bin/codegraph.js and fail with MODULE_NOT_FOUND until the documented npm run build step runs, after which all 21 affected files pass (114/114). Regression tests carry issue numbers (#456, #825, #1578, #1611), and the 332KB Keep-a-Changelog documents every release.

The benchmark reporting is the honest kind. The README publishes a 7-repo, 2-arm, 4-run-median benchmark (88% fewer tool calls, 62% fewer tokens) including the methodology: the harness blocks the codegraph CLI in both arms (they caught 26 of 28 control runs self-contaminating by finding the CLI on PATH and fixed the harness), and contamination is reported as 0 of 28. Then it discloses the counter-finding most vendors would bury: codegraph leaves about 80% more retrieval context resident in the window at session end (67k vs 18k tokens on VS Code), with a per-repo file committed in the repo. The eval harness itself is packaged as a repo-local skill (.claude/skills/agent-eval) so anyone can rerun it.

The Bad

The README documents a headline feature the shipped release does not have. codegraph ui, the browser viewer with its Screens tab, Steps tab, and flow strips, gets roughly 45 lines of README coverage, and v1.6.0 (released 2026-08-26, the latest) answers codegraph ui with error: unknown command 'ui'. The 22 shipped commands contain neither ui nor its web alias; the feature lives in the Unreleased CHANGELOG section. Nothing in the README marks it as unreleased, so every user following the main-branch README today hits an unknown-command error on a documented feature.

No CI runs the test suite. The repo has exactly two workflows: Release (manual dispatch, which runs only the kernel-*.test.ts subset before packaging) and Deploy site. There is no push or pull-request workflow at all, so the 4,240 tests that make this codebase credible run only on the maintainer's machine. For a 69K-star tool whose releases are otherwise attested and signed, this is the odd gap.

The MCP server negotiates down to the 2024-11-05 protocol revision. A probe requesting 2025-06-18 got back 2024-11-05 (spec-compliant downgrade, handled gracefully, and clients work fine), and capabilities advertise tools only, no resources or prompts. Not a functional problem on any client GearScope tested, but the newest spec revision is not offered.

The footprint is heavy and uninstall leaves a small residue. The self-contained bundle downloads 54.2MB and extracts to 278MB, an order of magnitude beyond a typical skill install. And after codegraph uninstall --target=hermes, the platform_toolsets: block with its - hermes-cli entry stays behind in config.yaml even though codegraph created that block during install (the - mcp-codegraph entry itself is correctly removed).

Telemetry is default-on. Anonymous usage stats (command names, language names, coarse counts) and a once-daily GitHub release check are on unless you opt out, via codegraph telemetry off, CODEGRAPH_TELEMETRY=0, or DO_NOT_TRACK=1 (all verified working, and the TELEMETRY.md field list is enforced by a public ingest endpoint in the repo). The disclosure is exemplary, but the default is still on.

Smoke Test Results

Host-based hands-on testing on macOS 26.5.2 aarch64 (sbx sandbox unavailable: Docker not authenticated). All runs used isolated HOME, HERMES_HOME, and install directories, with DO_NOT_TRACK=1 set. Three runs plus two supplementary checks; 33 of 33 checks passed.

Run A. Install (bundle installer, fresh)

$ sh install.sh (isolated CODEGRAPH_INSTALL_DIR + CODEGRAPH_BIN_DIR)
✅ PASS: install exit 0, launcher at $CODEGRAPH_BIN_DIR/codegraph
$ codegraph version
✅ PASS: 1.6.0 == GitHub tag v1.6.0 == npm dist-tags.latest
$ du -sh versions/
✅ PASS: 278M extracted (54.2MB darwin-arm64 tarball; SHA256 verified against release SHA256SUMS)
$ codegraph version (PATH with no node)
✅ PASS: runs on the vendored runtime, no system Node
$ codegraph help
✅ PASS: 22 subcommands listed
$ codegraph telemetry status
✅ PASS: "Telemetry: disabled (DO_NOT_TRACK environment variable)"
$ codegraph definitely-not-a-command
✅ PASS: exit 1

Pass rate: 7 of 7. The primary documented install path works first try, verifiable, and offline-safe after download.

Full log →

Run B. Server starts (index builds, graph is queryable)

$ codegraph init (6-file TS+Python fixture)
✅ PASS: exit 0 in 1s, .codegraph/codegraph.db 176K
$ codegraph status
✅ PASS: Files: 6, Nodes: 26, Edges: 50, Journal: wal
$ codegraph query UserRepo
✅ PASS: symbol found
$ codegraph explore "how does handlePostUsers reach UserRepo.save"
✅ PASS: 3-hop chain with file:line for every hop
$ codegraph callers findById
✅ PASS: lookupUser at src/service.ts:9
$ codegraph impact normalize
✅ PASS: "2 affected symbols" across the Python module
$ codegraph sync (after appending a new function)
✅ PASS: post-sync query finds nightshift
$ codegraph query fetch_score
✅ PASS: Python symbols in the same graph as TypeScript
$ codegraph explore "anything" (cwd with no index)
✅ PASS: clean guidance naming the fix, exit 1; the text explicitly tells AI agents not to run init themselves

Pass rate: 9 of 9. Index, query, traversal, impact, sync, and the unindexed-directory contract all behave as documented.

Full log → (10/10 on this run; an earlier run scored 9 of 10 because of a wrong exit-code assertion in the test script itself, not a product failure)

Run C. Tools respond (MCP + Hermes wiring)

$ initialize (MCP stdio handshake)
✅ PASS: serverInfo {"name": "codegraph", "version": "1.6.0"}; instructions present (1,147 chars)
$ tools/list
✅ PASS: single tool codegraph_explore by default, as documented
$ tools/call codegraph_explore {query: "how does handlePostUsers reach UserRepo.save", projectPath: fixture}
✅ PASS: route->service->db chain returned over MCP
$ tools/call codegraph_explore {projectPath: path-with-no-index}
✅ PASS: guidance text, no error dump
$ tools/list (CODEGRAPH_MCP_TOOLS=explore,node,search,callers,callees,impact,files,status)
✅ PASS: all 8 tools enumerated
$ codegraph install --target=hermes (isolated HERMES_HOME)
✅ PASS: config.yaml gains mcp_servers.codegraph AND platform_toolsets mcp-codegraph
$ codegraph install --target=hermes (config pre-seeded with model + another MCP server)
✅ PASS: upsert preserves all pre-existing entries
$ codegraph uninstall --target=hermes --keep-cli
✅ PASS: codegraph entries removed, other config intact (platform_toolsets block itself remains: see The Bad)
$ codegraph install --print-config hermes
✅ PASS: snippet printed, nothing written
$ npm registry check
✅ PASS: npm latest 1.6.0 == installed 1.6.0 == tag v1.6.0

Pass rate: 10 of 10. This is the badge run: the MCP surface a real agent consumes works end to end, and the Hermes integration round-trips cleanly.

Full log →

Scale check: the repo indexes itself

$ codegraph init (codegraph repo: 109K LOC TS + 24K LOC Rust + Svelte)
✅ PASS: 787 files, 16,905 nodes, 64,099 edges in 30s, 72MB db
$ codegraph explore "how does the MCP server register codegraph_explore"
✅ PASS: answered in 3s, 619 lines, blast radius with test-caller attribution
$ codegraph callers upsertCodeGraphMcpServer
✅ PASS: resolves to writeHermesConfig (the correct path)
$ codegraph files --filter node_modules (144MB of deps present)
✅ PASS: excluded from the index

Pass rate: 5 of 5. Full log →

Repo's own test suite

$ npx vitest run (bare clone, 236 files)
✅ 3,950 passed / 84 failed / 202 skipped of 4,240 in 130s; all 84 failures are MODULE_NOT_FOUND on dist/bin/codegraph.js (build step not yet run)
$ npm run build && npx vitest run (the 21 failed files)
✅ 114/114 passed

Combined: 4,064 of 4,064 non-skipped tests pass once the documented build runs. Logs: full run, post-build retry

What the runs tell you

The install path, the graph engine, the MCP surface, and the Hermes integration all work exactly as documented, on both a controlled fixture and a real 787-file codebase, with correct answers at every layer GearScope could assert on. What these runs cannot tell you is the live-agent experience: the auto-sync watcher inside a real session, and the token and cost savings in the benchmark table, which depend on model and workload and were not independently reproduced here.

Setup Walkthrough

1. Install the CLI: curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh (or npm i -g @colbymchenry/codegraph). The bundle lands in ~/.codegraph, a symlink in ~/.local/bin; open a new terminal.
2. Wire your agents: codegraph install, which auto-detects installed agents (all 9, including Hermes via ~/.hermes/config.yaml) and writes the MCP config. For scripting: codegraph install --yes --target=hermes or any csv list; --print-config previews without writing.
3. Build a project graph: cd your-project && codegraph init. One global install covers every project; init is per-project. Auto-sync is on by default afterward.
4. Optional: codegraph telemetry off if you want zero outbound traffic (DO_NOT_TRACK=1 also works and also stops the daily release check).

Post-install gotchas: the extracted bundle is 278MB; the README's codegraph ui section does not apply to v1.6.0 (unknown command); and if your Hermes profile uses an explicit platform_toolsets.cli list, the installer handles adding mcp-codegraph for you, which is exactly the failure mode a manual config would hit.

Alternatives

1. Graphify-Labs/graphify - 89.7K-star Python knowledge-graph skill with 34 tree-sitter grammars and a 10-tool MCP server, installed as a SKILL.md skill rather than a CLI. Prefer it when you want the graph inside the agent-skill ecosystem with progressive-disclosure references; prefer codegraph for installer-managed multi-agent wiring and a compiled kernel.
2. DeusData/codebase-memory-mcp - 42K-star persistent codebase memory layer. It answers "what do I know about this project" across sessions; codegraph answers "what code is involved in this change". The two abstractions overlap but do not replace each other.
3. optave/ops-codegraph-tool - 34-tool MCP server for function-level dependency graphs and CI gates across 34 languages. Smaller scope, smaller footprint, no installer layer; a reasonable choice when you want graph queries only in one agent and one repo.