v0.7.3 · MIT

Your assistant stops grepping and starts reading the graph.

GitCortex indexes your repository into a branch-aware knowledge graph on every commit, then serves it to AI coding assistants over MCP. It runs entirely on your machine: no cloud, no API keys, no LLM calls, no source code leaving disk.

$ brew install bharath03-a/tap/gitcortex
Get started View source
gcx · find_callers · branch main
// an assistant asks: what breaks if I change Session.send?
answer  3 production callers; change risk is medium.
evidence
  Session.request sessions.py:589 calls
  Session.get      sessions.py:602 calls
  Session.post     sessions.py:637 calls
coverage 3 of 3 · not truncated
typed resultfile:line evidenceone call, no follow-up

Latest

Release
v0.7.3 is out
Fixed every command defaulting to a hardcoded "main" branch, silently showing empty results on any repo using master/trunk/etc — plus a clean Ctrl-C fix for gcx viz.
Benchmarks
Measured across 3 real AI clients
Codex, Claude Code, and Agy — real token counts, not estimates, on deep blast-radius and refactor-safety questions.
Compare
How GitCortex compares to Graphify
A real, same-questions comparison against another open-source code graph — including where it beats us.
How it works

A typed graph, rebuilt incrementally by git itself.

Four git hooks keep the graph honest: post-commit, post-merge, post-rewrite, post-checkout. Each run diffs from the last indexed SHA rather than HEAD~1, so rebases and amends never leave the graph stale.

Everything nameable is a node

Struct · Enum Trait · Interface Function · Method Module · File TypeAlias Constant · Macro Section

Every relationship is a typed edge

Contains Calls Implements Uses Imports References
The explorer

Same schema, painted as a graph you can walk.

gcx viz serves the graph as a local web app: an atlas for orientation across the whole repository, and an investigation canvas for tracing one symbol's exact neighbourhood. Both run against your own indexed repository. These are real captures of GitCortex indexing itself.

gcx viz · atlas · force layout
GitCortex graph explorer showing an entire repository as a force-directed node graph, coloured by symbol kind
gcx viz · investigate · symbol selected
GitCortex graph explorer zoomed into a cluster of functions, with one symbol selected and its neighbours labelled
Design decisions

Built for repositories that cannot leave the building.

Local

No network path

KuzuDB runs embedded and the embedding weights are local. There is no server to call, so the tool works air-gapped and cannot leak source by design.

Incremental

Hook-speed indexing

Only changed files are re-parsed, diffed from the last indexed SHA. Re-running is idempotent, so a hook that fires twice costs nothing.

Branch-aware

One graph per branch

Each branch gets its own namespace, so switching branches switches context. branch_diff reports what changed structurally between any two.

Interoperable

MCP over bespoke APIs

gcx serve speaks the Model Context Protocol, so any compatible assistant queries the graph through structured tools instead of grep.

Capabilities

Parsing, retrieval, and analysis, all on your machine.

Multi-language AST parsing

A tree-sitter backend gives one parsing API across every supported language. Types, functions, methods, traits, calls, and imports are extracted structurally.

RustGoPythonTypeScriptJavaMarkdown

Ranked symbol search

Hybrid lexical and local-embedding search over names and qualified paths. Definitions rank above containers, test helpers, and documentation headings.

fastembed-rsBAAI/bge-smalllocal weights

Clustering and hub detection

Deterministic label propagation over Contains and Calls edges. find_clusters surfaces module groupings; find_god_nodes finds high-fan-in bottlenecks.

label propagationin-degree centralitydeterministic

Interactive graph explorer

An Axum-served React and Cosmograph front end, colour-coded by node kind, filterable and keyboard-navigable. Exports to HTML, SVG, DOT, and GraphML.

WebGLARIA roleskeyboard nav

Markdown ingestion

Headings become Section nodes and code-span mentions resolve to References edges, so documentation links are tracked in the same graph as the code they describe.

pulldown-cmarkNodeKind::SectionEdgeKind::References

Blast-radius reporting

Transitive caller analysis against a base branch, ranked production-first with tests reported separately, usable from the CLI or as a pull-request comment.

git2rayonKuzuDB embedded
Install

Five ways in. All of them ship a binary.

Pre-built binaries cover macOS on arm64 and x86_64, and Linux on x86_64 and arm64. On Windows, use WSL2. 

# macOS or Linux
brew install bharath03-a/tap/gitcortex

# Index a repository; add --editor <name> for opt-in MCP setup
gcx init

The official tap installs the matching pre-built binary. No Rust, Python, or Node.js runtime required.

MCP server

Structured tools, not a chat box.

Add gcx serve to your .mcp.json and any MCP-compatible assistant gains typed access to the graph.

  • lookup_symbol(name)Every definition matching a name, across the graph
  • find_callers(name)Ranked callers with file and line evidence
  • get_subgraph(name, depth)Bounded neighbourhood: callers, callees, implementations
  • search_code(query)Ranked hybrid search over names and qualified paths
  • find_god_nodes(min_in_degree)High-fan-in symbols: bottlenecks and hot modules
  • find_clusters(min_size)Label-propagation clusters over the call graph
  • branch_diff(from, to)Structural difference between two branches
  • start_tour(seed?)Guided walkthrough, centrality-ranked or seeded

.mcp.json (project root)

{
  "mcpServers": {
    "gitcortex": {
      "command": "gcx",
      "args": ["serve"],
      "env": {}
    }
  }
}

Works with Claude Code, Cursor, Windsurf, Continue.dev, and any other MCP host.

Measured

Claims you can reproduce, tracked release over release.

Every run below is reproducible from the scripts named in its methodology line. Numbers are not smoothed across runs: methodology changed between them, and each panel says how.

Deterministic, model-free retrieval gate over five pinned repositories (Rust, Python, TypeScript, Go, Java), plus one native Codex CLI smoke run.

1.00
Search MRR

Mean reciprocal rank on the pinned suite: every query returns a relevant definition in first position.

20 / 20
Tasks valid

Every task returns the required evidence, omits forbidden evidence, and stays inside its payload budget.

1.82×
Codex uncached tokens

Native codex exec graph-CLI lane on cobra, one round: uncached token geomean against a grep baseline.

This lane is model-free by design, so it is gated on every commit rather than run on a schedule. See the retrieval gate write-up and the full benchmark plan. Reproduce: python3 tools/agent-bench/bench.py run.

Index your first repository in about a minute.

Install the binary, run gcx init to wire up the hooks, and the graph maintains itself from then on.

Install GitCortex Read the reference