CodeGraph: a local code index for agents

Everything worth knowing about colbymchenry/codegraph: a local tool that turns a repository into a queryable graph via CLI, library, and MCP for coding agents.

What CodeGraph is

CodeGraph builds a pre-indexed knowledge graph of a repository: symbols, files, calls, imports, inheritance, and other relationships. It stores this locally in SQLite with FTS5 search and exposes it to an agent through an MCP server, plus a command-line interface and a Node.js API. According to the README and the official documentation, its purpose is to let an agent retrieve structural context and the scope of a change without reconstructing the architecture through many searches and file reads.

The tool declares support for Claude Code, Codex CLI, Cursor, OpenCode, Hermes Agent, Gemini CLI, Antigravity, and Kiro. It also states that it needs no API keys and that the graph stays on the machine. That is a product property documented by its author, not an independent privacy audit.

The origin: a solo project from 2026

GitHub’s API dates the repository’s creation to January 18, 2026. Its author and top contributor is Colby Mchenry (colbymchenry); his GitHub profile describes him as a professional with more than fifteen years building software. The npm package appeared the same day, according to its publication history.

The tension the project raises is concrete: an agent that needs to understand a codebase typically uses text search and file reads to infer call paths and dependencies. CodeGraph proposes inverting that order: build the index before the query, keep it in sync, and hand the agent a set of relevant symbols, code, and relationships. The README acknowledges an important limit: its lower-token and lower-cost figures measure processing and calls, but its dense responses can leave more context resident during long sessions.

Philosophy and principles

Local first: the .codegraph/codegraph.db store and the index live inside the project; the README states it sends no code or queries to an external service.

Depiction of an armored local server inside a protective dome, with no external connections, symbolizing the local-first approach.

Structural context before manual exploration: a query can return code, call paths, and impact radius, instead of leaving the agent to reconstruct the structure itself.
Incremental updates: the MCP server watches operating-system changes and syncs the index per file after a debounce window.

Visualization of an incremental-update pulse traveling through the code graph after a change is detected, with a debounce timer in the background.

A single entry point for the agent: the README leaves codegraph_explore as the default visible MCP tool; the narrower tools remain available but must be enabled explicitly.

An AI agent analyzing a call path between two functions on a three-dimensional projection of the code graph.

Verifiable distribution: since July 2026 the project has documented npm provenance and signed attestations for the files in its GitHub releases.

How it works

The documented technical flow has four phases:

A native Rust core parses a portion of the supported languages using Tree-sitter grammars; portable paths and files that can’t use the precompiled binary fall back to the alternate engine.
Extraction saves nodes and edges to .codegraph/codegraph.db, an SQLite database with FTS5.

Luminous SQLite core at the center of a graph architecture, surrounded by node, edge, and FTS5 search-index tables.

The resolver links calls to definitions, imports to files, inheritance, and web-framework patterns; the README lists routes for, among others, Django, FastAPI, Express, NestJS, Rails, Spring, Laravel, and several Go and Rust frameworks.
When the MCP server runs, a file watcher syncs changes. The documentation states a default debounce of two seconds, configurable via CODEGRAPH_WATCH_DEBOUNCE_MS; during that window, the response may note that a pending file should be read directly.

Version v1.5.0, released on July 21, 2026, added the Rust core for twenty languages along with adaptive worker and memory tuning. Its release notes claim sub-second sync on test repositories, but those are the project’s own measurements.

Official and semi-official status

No evidence was found of inclusion in an official marketplace from Claude, OpenAI, Cursor, or another provider. The integration is semi-official in a technical sense, not a commercial one: codegraph install detects configurations of the supported agents and registers the MCP server in them. That does not equate to certification, endorsement, or support from those providers.

The package is published on the official npm registry as @colbymchenry/codegraph. The documentation also links to a Homebrew repository from the same author, colbymchenry/homebrew-codegraph, but no official Homebrew formula was found, and its availability in the main catalog should not be inferred.

The ecosystem

colbymchenry/homebrew-codegraph (0 stars at query time): a repository described as a Homebrew repository for CodeGraph.
colbymchenry/shopify-graphql-admin-mcp (22 stars): another MCP server by the author, for connecting Claude to a Shopify store. It is a sibling project, not a CodeGraph dependency.
colbymchenry/frontend-audit-skill (19 stars): a visual-regression audit skill; also not a confirmed component of CodeGraph.
The repository itself contains codegraph-kernel, telemetry-dashboard, and telemetry-worker. These are directories inside the monorepo, not independent public repositories.

Forks, ports, and extensions

The forks API shows derivatives with explicit changes, as opposed to many mirrors that keep the original description:

A central CodeGraph hologram surrounded by satellite nodes representing community forks and ports, including Rust derivatives and a Hermes Agent port.

Cleboost/codegraph-rs (42 stars) describes itself as a low-overhead Rust implementation.
ingeniousfrog/CodeDelta (26 stars) states it visualizes structural changes and traces issue origins across commits.
nanofatdog/codegraph_hermes (9 stars) keeps the local-graph approach and mentions Hermes Agent.
IppearPeng/codegraphFD (2 stars) states it adds Fortran support.
zybk1003/codegraph (1 star) keeps a description translated into Chinese; it is a community fork, not a verified official translation.

The GitHub search also turned up projects in the same category, though not dependencies: CodeGraphContext/CodeGraphContext (4,054 stars) and Jakedismo/codegraph-rust (860 stars). The search found no affiliation with colbymchenry/codegraph.

Repository numbers

Measured: August 6, 2026, GitHub API and npm API.

Metric	Value
Stars	64,908
Forks	4,078
Real subscribers	147
Commits	825
Open issues per the API	393
Primary language per GitHub	C
License	MIT
Created	January 18, 2026
Last metadata update	August 6, 2026
Latest release	`v1.5.0`, July 21, 2026
npm downloads, last 7 days available	75,949
npm downloads, last 30 days available	336,711

The top contributors returned by the API were colbymchenry (731 contributions), github-actions[bot] (26), omonien (16), andreinknv (7), and MO2k4 (4). The commit count of 825 comes from the last page of the API’s pagination link. open_issues_count may include open pull requests. The general response’s watchers_count field duplicates the star count, so subscribers_count is reported here as real subscribers.

How to contribute

No CONTRIBUTING.md or pull-request template was found in the public paths checked. There are tests (__tests__), a Vitest configuration, and GitHub workflows, but the retrieved sources don’t document a contribution flow, a target branch, or review requirements. So no process should be assumed: before contributing changes, it’s worth opening an issue or checking the repository for the current criteria.

How the community received it

The recoverable external evidence is limited and should be kept separate from the project’s own claims:

The direct Hacker News submission 49054696, titled with the project’s name and submitted by handfuloflight on July 26, 2026, had 5 points and 0 comments. That shows reach, not a review or community enthusiasm.
In thread 48994388, with 2 points and 1 comment, user pankaj4u4m, the self-described maintainer of LemonCrow, posted a comparison. They claimed that across their 35 runs, CodeGraph cut total cost by 16.3%, less than the token reduction they discussed. They also claimed a lower MRR figure than their own product. The comment’s author themselves notes this isn’t an independent review and says they asked for a configuration review, so these are attributed results, not a confirmed benchmark.
The README publishes its own benchmark, re-measured on August 5, 2026 across seven repositories, claiming 88% fewer calls, 53% less time, 62% fewer tokens, and 44% lower cost at the median. Its methodology and repositories are described in the README, but no external replication was found; these should be read as the project’s own results.

Two bar charts comparing a standard agent against a CodeGraph-equipped agent on calls, time, and cost, with the CodeGraph agent showing much lower values.

Reddit searches in the requested subreddits returned no content retrievable past the site’s automated protection. Queries on X, Product Hunt, and YouTube likewise produced no verifiable post, launch page, or video for this project. DEV Community showed a search page, with no identifiable article about the repository. No verifiable mention in newsletters or podcasts was found, nor a verifiable inclusion in an awesome-* list.

CodeGraph versus other proposals

Proposal	Verifiable overlap	Verifiable difference
`CodeGraphContext/CodeGraphContext`	An MCP server and CLI that indexes local code into a graph for AI assistants.	Its public description talks about a graph database; CodeGraph documents SQLite, FTS5, and an installer for several agents.
`Jakedismo/codegraph-rust`	A code graph and agent tooling via MCP.	Its description mentions SurrealDB, AST analysis, and FastML; it is not a confirmed port of CodeGraph.
`optave/ops-codegraph-tool`	A local code-intelligence CLI with MCP and change impact.	It declares 34 MCP tools and architecture/CI controls, while CodeGraph leaves a single MCP tool visible by default.
`LemonCrow`	Both are presented as tools for optimizing agent context and cost.	The retrieved performance comparison comes from LemonCrow’s maintainer and is not an independent measurement.

Quick usage guide

Installation and first run

On macOS or Linux, the README points to this standalone installer; on Windows it offers the PowerShell equivalent:

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# In a new terminal:
codegraph install
cd your-project
codegraph init

It can also be installed via npm:

npm i -g @colbymchenry/codegraph

Terminal running the codegraph install and codegraph init commands, with icons of supported AI agents automatically detected.

The installer bundles its own runtime, so the README states that neither the CLI nor MCP requires Node.js. codegraph install configures the detected agents but does not index any project; codegraph init creates .codegraph/ and builds the index. After installing, a new terminal must be opened for the executable’s path to become available.

Common workflows

To get context for a task, run codegraph explore "how does X reach Y"; it returns symbols, code, call paths, and an impact-radius summary.
To evaluate a change before editing, use codegraph impact <symbol>; to see potentially affected tests, codegraph affected <files...>.
For a one-off query, use codegraph query <search>; codegraph callers <symbol> and codegraph callees <symbol> walk the direct relationships.
The index updates automatically while working through MCP. If the watcher is disabled or automation runs outside an agent session, run codegraph sync [path]; codegraph status [path] shows the state and any pending files.

Essential configuration

.codegraph/: a per-project directory; it holds the local index and can be removed with codegraph uninit.
codegraph.json: an optional file for exclude, include, and includeIgnored; it’s used to tune what code enters the index.
.gitignore: respected by default; a negation like !vendor/ can reintroduce an excluded path where the tool supports it.
CODEGRAPH_WATCH_DEBOUNCE_MS: adjusts the maximum wait before syncing changes; the README caps it between 100 ms and 60 s.
CODEGRAPH_MCP_TOOLS: re-exposes additional MCP tools, for example explore,node,search,callers.

Common pitfalls and fixes

Installing is not the same as indexing: if the agent can’t find the project, run codegraph init from the root; install only wires up agents.
The command doesn’t show up in the same console: open a new terminal after running the installer.
A stale lock blocks indexing: use codegraph unlock [path] per the CLI reference.
A freshly edited file may not be in the graph yet: during the debounce window, read it directly or check codegraph status; for automation without a watcher, use codegraph sync.
Too much or too little gets indexed: review .gitignore and codegraph.json. Dependency, build, and cache directories, along with files larger than 1 MB, are excluded by default.

Integrations and migration

codegraph install registers the MCP server for the detected supported agents; the intended integration is MCP, not an editor-exclusive plugin. To undo it, codegraph uninstall removes configurations and the CLI; codegraph uninstall --keep-cli keeps the executable. Project indexes are not removed by that command and are removed separately with codegraph uninit. The documentation does not describe an automatic migration from CodeGraphContext, LemonCrow, or another comparable tool.

To embed it as a library, install it from npm and use Node 22.5 or later; the README offers CodeGraph.init('/path/to/project'), indexAll(), searchNodes(), getCallers(), and getImpactRadius().

Use cases and who this repository can help

People adding agents to an existing repository can initialize the graph and ask about a path, symbol, or flow, getting code and relationships back instead of starting with file-by-file text search.
Teams reviewing changes with propagation risk can use impact, callers, callees, and affected to investigate dependencies and tests the change might reach; actual coverage depends on the languages, frameworks, and patterns the documentation lists.
Polyglot repositories, or ones with a web layer and a native layer, can benefit from multi-language extraction and the relationships the project claims for framework routes, Swift/Objective-C bridges, and React Native/Expo. It’s worth validating coverage against your own code, especially for unsupported syntax.
Teams that want to keep analysis inside their own environment can use the local SQLite database and MCP configuration without API keys, while keeping in mind the optional telemetry: it can be disabled with codegraph telemetry off, CODEGRAPH_TELEMETRY=0, or DO_NOT_TRACK=1.

Resources

Repository: https://github.com/colbymchenry/codegraph
Official documentation: https://colbymchenry.github.io/codegraph/
Installation and CLI reference: https://github.com/colbymchenry/codegraph#quick-start
Changes and releases: https://github.com/colbymchenry/codegraph/releases and https://github.com/colbymchenry/codegraph/blob/main/CHANGELOG.md
npm package: https://www.npmjs.com/package/@colbymchenry/codegraph
Core code and tests: https://github.com/colbymchenry/codegraph/tree/main/codegraph-kernel and https://github.com/colbymchenry/codegraph/tree/main/__tests__
Discussions and comparisons: https://news.ycombinator.com/item?id=49054696 and https://news.ycombinator.com/item?id=48994388
Community/Discord: no verifiable official link was found.

Note: this article combines CodeGraph’s README, documentation, and releases, the GitHub API, the npm registry and downloads API, and Hacker News, all checked on August 6, 2026. Figures change over time.