Repository navigation
Releases
CodeGraph v1.3.0-beta.1
A pre-release, the first with the VS Code extension. GitHub's latest release stays 1.2.0, so the installers and the
Claude Code plugin keep installing 1.2.0 unless given --version v1.3.0-beta.1 (-Version on Windows).
- A tag with a
-suffixis published as a pre-release, and its release notes name the tag in the install commands. - The extension installs its own release while GitHub's latest is older, because 1.2.0 lacks
codegraph-index statusandstop. It ranks a pre-release before its release (1.3.0-beta.1 < 1.3.0), so it offers 1.3.0 once
that is out.
VS Code extension
-
A VS Code extension (vscode-extension/README.md) installs CodeGraph, sets
repositories up, and runs each graph's live daemon. It shows each graph's state in an Overview, a Graphs tree and
the status bar.- It installs from the GitHub release after checking the archive against
SHA256SUMS, and checks for a newer
release once a day. It unpacks the release beside the install folder and then swaps the two folders, so a
failed update leaves the old installation whole. It never replaces a folder that holds other programs (a
codegraph-indexonPATHin~/.local/binis followed to its own folder, or the default folder is used). - A graph takes one target of each language, because an index replaces all of a language's rows. A second
TypeScript workspace or C# solution in the same repository shows as not indexed, and indexing it asks first.
A solution hides only the projects it lists. - It starts a daemon with
--idle-exitfor each graph that exists, and stops the daemons it started when the
window closes. - It re-indexes on save the targets the daemon does not watch, such as an Angular front end beside a C# solution.
- It offers
codegraph-mcpto VS Code's chat clients, unless.vscode/mcp.jsonalready names one. - Each release carries it as
codegraph-vscode.vsix. It is not on the Marketplace.
- It installs from the GitHub release after checking the archive against
-
Tested: 13 unit tests, and an integration test that drives the extension inside VS Code 1.146.0 against the
indexer built from this repository. It runs 7 steps: find the solution, index it, see an edit go stale, start the
daemon and wait for it to index the edit, stop it, and rebuild. CI run 43972862634 (16 November 2026) passed the
9 unit tests of that commit and all 7 steps on Linux, macOS and Windows; after the review fixes, CI run
44033732682 (17 November 2026) passed all 13 unit tests and all 7 steps on all three.- An 8th step checks the MCP server the extension offers. It starts the server with the offered arguments, calls
graph_statsand gets the graph's counts. It also checks that a.vscode/mcp.jsonentry withdraws the offer
and that removing the entry brings it back. - An install test installs the 1.2.0 release with the extension's code, then updates it while
codegraph-mcp
runs from the folder: refused with nothing changed on Windows, replaced on macOS and Linux. - CI run 44035151104 (commit
9b623cf, 17 November 2026) passed both on Linux, macOS and Windows, with all
13 unit tests and all 8 steps.
- An 8th step checks the MCP server the extension offers. It starts the server with the offered arguments, calls
-
codegraph-index status [--db PATH] [--json]reports, in one call:- the graph and how it compares with the working tree: edited and deleted files, and a moved HEAD;
- nodes and files for each language, with each language's compiler facts;
- the daemon serving the graph;
- the last 7 days of tool calls.
With
--jsonit is for tools; the extension reads it. -
A graph file that is not a DuckDB database fails to open at once. Before,
GraphStore.Openretried it as if it
were locked, every 100 ms for the whole wait:codegraph-index statustook 5 s to say the file was damaged, and
the test for that took 5.06 s and now takes 36 ms. On macOS CI the whole suite stalled the runner on this branch
until this changed; a macOS bisect passed the suite when that test was left out (and when either of two others
was), and three runs of the whole suite passed after the change. -
Both daemons answer a
statusrequest likeping, but it does not reset the idle-exit clock;
codegraph-index statususes it, so the extension's poll every 15 s no longer keeps an unused daemon running.
A daemon from 1.2.0 or earlier does not know it and is asked withping. -
Index runs on one graph take turns across processes: each holds
graph.db.lockfrom reading the old graph to
swapping in the new one. Before, the daemon re-indexing C# and an import of the TypeScript rows could overlap,
sharegraph.db.tmp, and drop rows the other had just written. -
codegraph-index stop [--db PATH]asks the daemon serving a graph to stop and waits until its pipe is gone. Both
daemons, C# and the language-server one, answer a newstoprequest on the pipe. A daemon from 1.2.0 or earlier
does not know it:stopsays so, names its process id, exits 1 and leaves it running.
Install
This is a pre-release. The installers install the latest full release unless given a tag, so the commands
below name this one. The Claude Code plugin installs the latest full release.
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/nerdcules/CodeGraph/main/codegraph/install.sh | bash -s -- ~/dev/YourApp --add-to-path --version v1.3.0-beta.1Windows (PowerShell):
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/nerdcules/CodeGraph/main/codegraph/install.ps1))) C:\dev\YourApp -AddToPath -Version v1.3.0-beta.1Or download the archive for your platform below, unpack it anywhere, and run codegraph-index init in a repository.
SHA256SUMS holds the checksum of each file. The executables are not code-signed; on macOS, run
xattr -dr com.apple.quarantine <folder> on a folder unpacked from a browser download.
CodeGraph v1.2.0
Any MCP client
codegraph-index init --client <names>writes the server's config for other assistants.copilotcovers every
GitHub Copilot that reads a project's servers: the CLI (.mcp.json), VS Code (.vscode/mcp.json), Visual
Studio (.vs/mcp.jsonbeside the solution) and JetBrains IDEs (.github/mcp.json); each also has its own name.
The others:cursor(.cursor/mcp.json),gemini(.gemini/settings.json),codex(its global config,
throughcodex mcp add, keeping hand-added env), and the AI extensionsroo(.roo/mcp.json),kilo
(.kilo/kilo.json, in opencode 1.x's shape) andcontinue(.continue/mcpServers/codegraph.json).
claude(.mcp.json) stays the default;allwrites every one. Other servers and settings in those files are
kept; a re-run with nothing new changes nothing.install.sh --clientandinstall.ps1 -Clientpass it on.codegraph-mcp --root DIR(orCODEGRAPH_ROOT) finds the graph fromDIRinstead of the working directory,
for IDEs that do not start servers in the project. VS Code and Cursor get--root ${workspaceFolder}; Visual
Studio and JetBrains, which neither start servers in the project nor expand variables, get the absolute
worktree root. A placeholder left unexpanded, as the Cursor CLI does, is ignored.- Checked with real tool calls from the Cursor IDE 3.29 (
${workspaceFolder}expanded), Copilot in VS Code 1.146 (agent mode,${workspaceFolder}expanded), the Codex
VS Code extension 26.1111 (it starts servers in the workspace, so the global entry needs no root), the Codex CLI
and the GitHub Copilot CLI, and the Cursor CLI (headless runs needMcp(codegraph:*)allowed in
.cursor/cli.json; the docs say how). Where each client starts its servers and which variables it expands was
read from the Roo Code, Kilo Code and Continue sources, and the Visual Studio and Copilot for JetBrains docs and
issue tracker. - Tests guard what their framework runs around them. In C#, a test now calls its class's constructors (instance
and static),Dispose/DisposeAsync,IAsyncLifetime.InitializeAsync, and methods marked[SetUp],
[TearDown],[OneTimeSetUp],[OneTimeTearDown](NUnit),[TestInitialize],[TestCleanup],
[ClassInitialize],[ClassCleanup](MSTest), on the class and its base classes. A run-time check found the
gap: on release 1.1.0, 44 tests executeGraphStore.Replaceandimpact_ofnamed 37 (all real); 5 of the
missing ones reach it only throughIndexFreshnessTests' constructor. With this change it names 42 of the 44.
The other 2 run the indexer as a child process, which a static graph cannot see. - A damaged graph file no longer crashes the indexer. An incremental run that cannot read the old graph rebuilds
it from source;--full(which read the old file to keep other languages' rows) skips what it cannot read. Both
say so. Before, both aborted, and the only cure was deleting the file. - A tool call that fails says why. A missing or mistyped argument gets the problem and the tool's parameters
("impact_of takes: id (string, required), depth (integer, default 5)"); a damaged graph file gets the command
that rebuilds it. Before, every one was "An error occurred invoking 'x'". - BENCHMARKS.md round 13: a full index of this repo took 16.7–17.6 s against round 12's 16.2–16.3 s, which the
round puts down to the graph's growth; Jellyfin's took 44.9–45.0 s by the indexer's own figure (round 12's 44.3–45.3 s did not record which figure); parity clean; and a resilience battery
(tools/CodeGraph.Bench/resilience.py, 12 of 12 after the two fixes above). It found the graph file creeping
under the live daemon, about 3 MB over the last 50 of 100 saves; fixed below. A later Linux run of the battery
(round 15) passed 11 of 12: R4 had 8 errors, and their cause is open. The Windows re-test passed 12 of 12, and so
did the first macOS run (round 16). R4 run on its own 26 more times, on Linux, Windows and macOS, idle and under CPU
load, had no error (round 16). - An incremental pass writes only the rows that changed. Before, it deleted and re-inserted every row of each
re-walked file and project file, and all the stamps and meta. DuckDB rewrites every row group and index those
touch, so under--watchthe file grew with each pass and kept creeping. Over 150 saves on this repo: 1.1.0
went from 32.3 to 51.0 MB, still rising; this build stays at 30–38 MB, with no trend. A no-op pass on Jellyfin
now adds 2 MB instead of 47. After the passes, the graph equals a fresh full index in every table, on both
repos. BENCHMARKS.md round 14 has the figures;tools/CodeGraph.Bench/file-growth.shrepeats them. - Windows 11, checked by a Claude Code session there (BENCHMARKS.md round 15): 425 tests passed, 3 skipped; graph
swaps under a reading server, a from-source install and the uninstall in PowerShell 7 and 5.1, and the live
daemon all worked.
It found four things, now fixed:- With only a newer SDK installed (.NET 11), the indexer died with an unhandled MSBuildLocator exception. It now
says to install the .NET 10 SDK, or to setDOTNET_ROLL_FORWARD=LatestMajorfor a build from source. - A project whose NuGet packages were never restored, such as a fresh clone, indexed incompletely with no clear
warning when the framework still resolved. It now gets a note saying to rundotnet restore. A pass that
walks no file keeps the last walk's compile errors and notes instead of writing zeros over them. resilience.pyruns on Windows (noSIGKILLthere), and reads the node count after a stale-index warning.uninstall.ps1under Windows PowerShell 5.1 keeps the 2-space layoutinitwrites, rather than rewriting
every line in 5.1's own layout.
A second run there, atd3350b3, confirmed the restore note, the kept compile errors, the 5.1 layout and the
battery (12 of 12 with no shim). It found two more:- The live TypeScript test failed on Windows: it read the daemon's log while the daemon held it open for
writing. It now opens the log sharing read and write. The next Windows CI run got past the log and failed on
the references: each had no enclosing member. The language server sendsfile:///d%3A/…(drive letter
lower-case, colon encoded), which .NET read asD:\d:\…, and the graph's paths areD:\…. On Windows the
live tools now drop the slash before the drive, upper-case it, and compare paths without case. The same
mismatch hid every diagnostic fromcheck_changeanddiagnosticson Windows and made the language server's
start-up wait run out (66.6 s); diagnostics are now stored under the same URI form they are looked up by.
The live TypeScript test then passed in Windows CI (run 43702208790).
A third run there, ataf1eab5, passed the suite (440, 1 skipped) and the battery (12 of 12), and found two more: install.ps1read an unknown option, such as the retired-ObsidianVault, as a repo, and installed into the
default folder. It now stops with "unknown option" before it downloads or writes anything.- The daemon's
--logfile held its progress spinner (322 of 513 lines).--lognow turns the spinner off.
A fourth run there, atef202fe, confirmed both: unknown options stop the install in pwsh 7 and 5.1, and the
daemon's log had no spinner frame in 47 lines. uninstall.ps1anduninstall.shname each file and folder they remove, not just "entry removed".
- With only a newer SDK installed (.NET 11), the indexer died with an unhandled MSBuildLocator exception. It now
- The server accepts the id under the names models guess for it (
symbolId,nodeId,memberId, and their
snake-case forms, oridfor the tools that takesymbol). A Cursor agent passedsymbolIdto every tool, got
only "An error occurred invoking", and answered without the graph. - tools/eval: four assistants (Claude Code, Codex CLI, Copilot CLI, Cursor CLI), three runs
each with and without CodeGraph, on a copy of this repo without its docs, scored against a run-time answer key.
With CodeGraph 7 of 12 answers gave a test total (each 42, the graph's count; 44 tests execute the method);
without it none did. Claude Code was faster and cheaper with it; Codex and the Copilot CLI were not, and
Cursor's runs varied too much to call. Summary in
Why it saves tokens. - The server accepts an id with the brackets its answers print around ids (
[M:App.Run]): a Cursor agent
copied them and got "no node with id". The server's instructions now say to drop them. find_symbolwithnameMatch: Exactalso takes a qualified tail of the full name without its parameter list:
GraphStore.ReplacefindsCodeGraph.Core.GraphStore.Replace(bool, …). A Cursor agent tried exactly that,
found nothing, and fell back to two broader searches. The in-memory and SQL paths agree (parity tests).- The uninstall scripts remove the entry from every config
initcan write, and from Codex. - The README and docs say "your AI coding assistant" rather than Claude Code alone; the usage page lists each
assistant's instructions file. Tested with lists the assistants that
answered with real tool calls, and docs/client-tests has the configuration, tool
calls and answer of each run. - The promo video (118.6 s) says "your AI coding assistant", and a new card lists the assistants it was tested with.
The on/off sessions are still Claude Code. Its token figures are now the two measured sessions (180,134 against
459,907 input tokens), not the README's example week or the size of the matching files. - [Why it saves tokens](https://github.com/nerdcu...
CodeGraph v1.1.0
Faster reads
- The MCP server and the web view hold the graph in memory (
GraphSnapshot): node records and adjacency arrays
in both directions, loaded in the background at start and after every re-index. Finds, walks, tests, coverage,
dead code, paths and subgraphs answer from it; the database is opened only for full-text search, vectors and
metadata. Until a snapshot matching the file has loaded, calls read through DuckDB as before.
On Jellyfin (21,174 nodes), through the server at a model's pace:impact_ofdepth 20 from 860 ms to 9.7 ms,
covered_bydepth 30 from 1,173 ms to 5.1 ms,find_symbolfrom 42 ms to 8.8 ms.CODEGRAPH_SNAPSHOT=off
turns it off;index_statussays which path answers. - The recursive SQL stays as the reference: parity tests run every read both ways over random graphs, and
codegraph-bench --parity Ndoes the same over a real graph (0 differences in 6,096 checks on Jellyfin).
SQL orderings now break ties by id, so both answer in one defined order. - The freshness check reads HEAD from
.git(loose refs,packed-refs, linked worktrees) instead of starting
git rev-parseon most calls; it falls back to git for anything unusual, such as a reftable repository. codegraph-benchtimes every query through DuckDB and from the snapshot, and with--servertimes real
tool calls through one or morecodegraph-mcpbuilds over stdio.
Docs
- Every figure re-measured on 14 November 2026 (BENCHMARKS.md, round 12): this repo is now
3,119 nodes and 405 tests, the README's question answers 12 dependents and 37 tests in about 3 ms, and costs
about 5,500 tokens against about 123,000. A save reaches a fresh answer in about a second on this repo, not
"well under a second" as the docs said: the graph doubled since that was measured. - New Obsidian screenshots; redrawn live-daemon and index-time charts; an install diagram that shows the release
download rather than the build from source; a corpus chart that no longer cuts off the Rust line. Jellyfin,
NestJS, RealWorld and the corpus's large profile were measured again for the performance page. tools/corpus/run.pymounts whichever ofGOBINandGOPATH/binholds scip-go. Under mise,GOBINis Go's own
bin and every Go run failed with "scip-go is not on PATH".tools/obsidian-e2e/screenshots.pyapproves the repo's.mcp.jsonentry, asrun_e2e.shdoes. Without it
every panel in the screenshots saidspawn codegraph-mcp ENOENTand the run stopped at Find symbol.- The promo video shows the new figures. Its two sessions were run again headless (
claude -p, Claude Opus 5.5, effort
high, Auto mode) and are replayed from their transcripts: with CodeGraph, 42 s, 4 API calls, 180,134 tokens processed and
exactly 37 tests; without, 87 s, 9 calls, 459,907 tokens and "about 40". The README's GIF is the first of them.
Install
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/nerdcules/CodeGraph/main/codegraph/install.sh | bash -s -- ~/dev/YourApp --add-to-pathWindows (PowerShell):
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/nerdcules/CodeGraph/main/codegraph/install.ps1))) C:\dev\YourApp -AddToPathOr download the archive for your platform below, unpack it anywhere, and run codegraph-index init in a repository.
SHA256SUMS holds the checksum of each file. The executables are not code-signed; on macOS, run
xattr -dr com.apple.quarantine <folder> on a folder unpacked from a browser download.
CodeGraph v1.0.0
The first packaged release. Everything below was built between August and November 2026.
Install
- Prebuilt archives for Linux, macOS and Windows on x64 and arm64, each with its own .NET runtime, the
TypeScript extractor and its packages.install.shandinstall.ps1download the one for your platform,
verify its checksum and set up a repository;--from-sourcebuilds a checkout as before. - The Obsidian plugin ships as
codegraph-obsidian.zip. codegraph-index initwrites the repository's.mcp.json, ignores.codegraph/and builds the first graph.
Graph
- C# through Roslyn, in process; TypeScript, JavaScript and Angular through the TypeScript compiler; Java,
Kotlin, Scala, Go, Rust and Python through their SCIP indexers. One graph holds several languages. - Calls, references, inheritance, implementation, overrides, tests, project dependencies and framework
entry points as compiler-resolved edges. A call to an interface member counts for every implementation. - Incremental re-indexing by file hash; a full rebuild swaps a fresh file in with one rename.
- Each language records its compiler, the language versions the code uses and the errors it hit, so
index_statussays when a repository is newer than the compiler that read it.
Tools
- 35 MCP tools over stdio: find, callers, callees, impact, tests, dead code, full-text and semantic search,
graph statistics and usage statistics. - Every answer is checked against the working tree first and marked
STALEwhere it is behind. - Walk answers are capped at the nearest 200 rows per depth, with a count of the rest.
Live
codegraph-index --watchkeeps the compiled solution in memory, re-indexes a save in well under a second
and answerscheck_change,rename_preview,diagnostics,live_referencesanddata_flowover a pipe.- For TypeScript, Java, Go, Rust and Python the same tools go through the language server when one is on PATH.
Tested
- 390 .NET tests, 11 extractor tests and the Obsidian plugin's tests run on every push on Linux, macOS and Windows.
- A generated corpus in eight languages, with an answer key, scores precision and recall at 100% on current
toolchains in a modern and a classic dialect, and on older SDK images in Docker (.NET 8, Node 20, JDK 17,
Go 1.21, Rust 1.70, Python 3.8). BENCHMARKS.md has every number.
Install
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/nerdcules/CodeGraph/main/codegraph/install.sh | bash -s -- ~/dev/YourApp --add-to-pathWindows (PowerShell):
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/nerdcules/CodeGraph/main/codegraph/install.ps1))) C:\dev\YourApp -AddToPathOr download the archive for your platform below, unpack it anywhere, and run codegraph-index init in a repository.
SHA256SUMS holds the checksum of each file. The executables are not code-signed; on macOS, run
xattr -dr com.apple.quarantine <folder> on a folder unpacked from a browser download.