gitcortex 0.3.0

Git-aware code knowledge graph — incremental AST indexing on every commit, MCP server for AI assistants
gitcortex-0.3.0 is not a library.

GitCortex

A local-first, branch-aware code knowledge graph for Git repositories.

License: MIT crates.io npm PyPI CI

GitCortex (gcx) indexes your codebase incrementally on every commit using tree-sitter AST parsing, persists the graph in an embedded KuzuDB database, and exposes it to AI coding assistants via an MCP server — in Cursor, Claude Code, Windsurf, GitHub Copilot, and Google Antigravity.

cargo install gitcortex   # or: npm i -g gitcortex · pip install gitcortex
cd your-repo && gcx init  # index + install hooks + register your editor

Contents: Why · Demo · How it works · Install · Quick start · Commands · Languages · MCP · Graph schema · Architecture · Limitations & roadmap · Contributing

Why

When you ask an AI editor to work on a large codebase, it either scans dozens of files to build context (burning tokens) or misses the bigger picture entirely. There's no middle ground.

GitCortex gives your AI editor a pre-built, queryable call graph of your repo — functions, structs, traits, interfaces, call relationships, inheritance — so instead of reading raw source files it can ask precise questions like "what calls this function?" or "what implements this trait?" and get structured answers instantly.

Highlights

  • MIT licensed — commercial-friendly.
  • Zero runtime dependencies — single static binary, no Node.js / Python runtime required.
  • 5 languages — Rust, Python, TypeScript/JavaScript, Go, Java (coverage matrix).
  • Auto-indexing on every git op — incremental, sub-500 ms on changed files; a full index of a 520k-LOC repo (Django) takes ~4 s.
  • Per-branch graphs — switching branches is instant, no re-index.
  • Wiki, search, tour, blast-radius — built-in discovery surface for AI assistants and humans.
  • Works in Cursor, Claude Code, Windsurf, GitHub Copilot, Google Antigravity via MCP.

Demo

Demo video coming soon — see docs/demo.mp4 once recorded.

How it works

  1. gcx init installs four git hooks and runs an initial full index.
  2. On every local HEAD change the hook fires, diffs only the changed files, and updates the graph in under 500ms.
  3. gcx serve starts an MCP server on stdio so Claude Code (or any MCP client) can query the graph.
  4. gcx viz opens an interactive force-directed graph in your browser.

The graph is namespaced per branch — switching branches instantly gives you the graph for that branch with no re-indexing.

Supported languages

All five languages parse into the same graph schema (nodes + edges) and work with every query, the MCP tools, and the visualizer. Coverage maturity differs by language — the table is honest about what's deep vs. still shallow.

Language Defs (fn/type/method) Calls Inheritance Imports Notes
Rust ✅ ✅ ✅ traits/impls ✅ Reference implementation; deepest coverage.
Python ✅ ✅ ✅ base classes ✅ Decorators, async, generators, nested classes, properties, module-level bindings.
TypeScript / JavaScript ✅ ✅ ✅ extends/implements ✅ Generics, arrow-fn consts, type aliases, getters/setters. Visibility from export.
Go ✅ ✅ ◑ embedding ✅ Methods bind to receiver types. Structural interface satisfaction is not inferred (see roadmap).
Java ✅ ✅ ✅ extends/implements (incl. generics) ✅ Member annotations + fields not yet modeled (see roadmap).

Call resolution is syntactic (no full type inference): a call to a name with more than a handful of same-named definitions is treated as ambiguous and left unlinked rather than fanned out to all of them. This keeps the graph precise and the index fast.

Adding a language is a self-contained task — implement one LanguageParser in gitcortex-indexer. See CONTRIBUTING.md.

Requirements

  • Git
  • Rust 1.80+ (only needed for source installs — pre-built binaries require nothing)

Installation

npm / pnpm / yarn (Node.js — no Rust required):

npm install -g gitcortex
# or
pnpm add -g gitcortex
# or
yarn global add gitcortex

pip / pipx / uv (Python — no Rust required):

pip install gitcortex
# or (isolated, recommended for CLI tools)
pipx install gitcortex
# or
uv tool install gitcortex

macOS / Linux — curl installer:

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/bharath03-a/GitCortex/releases/latest/download/gcx-installer.sh | sh

Pre-built binaries for macOS (arm64/x86_64) and Linux (x86_64/aarch64) are published automatically on every release via GitHub Releases.

Windows is not currently supported — the embedded graph store (KuzuDB 0.11.3, upstream archived) does not link cleanly on MSVC. We'll restore Windows support after migrating the store layer.

Cargo (from crates.io):

cargo install gitcortex

Build from source:

git clone https://github.com/bharath03-a/GitCortex
cd GitCortex
cargo build --release
./target/release/gcx --help

Quick start

cd your-repo
gcx init

That installs the git hooks and indexes the current branch. Every subsequent commit updates the graph automatically.

Commands

gcx init

Installs four git hooks, runs the initial full index, registers the MCP server in the detected editor(s), and writes .gitcortex/AGENT_GUIDE.md as a universal context file.

gcx init                      # auto-detects editor(s) from environment
gcx init --editor cursor      # explicit target: claude, cursor, windsurf, copilot, antigravity
gcx init --editor all         # write configs for every supported editor
gcx init --ci                 # also writes .github/workflows/gcx-blast-radius.yml

Output:

GitCortex initialised  (820ms)
  Graph:     2 141 nodes | 5 328 edges
  Hooks:     4 git hooks installed
  Editors:   Cursor, Claude Code (auto-detected)
  Universal: .gitcortex/AGENT_GUIDE.md
Editor Files written
Claude Code .claude/hooks/, .claude/settings.json, .claude/skills/, .claude/commands/, ~/.claude.json
Cursor .cursor/rules/gitcortex.mdc, .cursor/mcp.json
Windsurf .windsurfrules, ~/.codeium/windsurf/mcp_config.json
Copilot .github/copilot-instructions.md
Antigravity ~/.antigravity/mcp.json

gcx hook

Called automatically by the git hooks — you rarely invoke this directly.

gcx hook                   # post-commit / post-merge / post-rewrite
gcx hook --branch-switch   # post-checkout (no re-index, just updates branch pointer)

gcx serve

Starts the MCP server on stdio. Wire this up in your .mcp.json to give Claude Code access to the knowledge graph.

gcx serve

gcx query

One-shot CLI queries for manual inspection. The same surface is exposed to AI assistants as MCP tools.

# Locate symbols
gcx query lookup-symbol MyStruct
gcx query search auth --limit 10              # ranked fuzzy match
gcx query list-definitions src/lib.rs

# Call graph
gcx query find-callers process_request --branch main --depth 3
gcx query find-callees handle_request
gcx query trace-path entry_point database_query
gcx query symbol-context apply_diff           # 360° view (def + callers + callees + uses)

# Discovery — new in v0.3
gcx query wiki apply_diff                     # markdown wiki page for a symbol
gcx query tour --limit 12                     # centrality-ranked global tour
gcx query tour --seed main                    # BFS-walk outward from a seed

gcx viz

Visualise the knowledge graph.

gcx viz                            # open interactive browser UI (default port 5678)
gcx viz --port 9000                # custom port
gcx viz --branch feat/auth         # visualise a different branch
gcx viz --format dot > graph.dot   # export Graphviz DOT to stdout
dot -Tsvg graph.dot -o graph.svg   # render with Graphviz

The browser UI is a React 19 + Vite + Tailwind v4 single-page app, rendered by Cosmograph (@cosmos.gl/graph) — a WebGL/GPGPU force-directed graph engine that runs the entire simulation on the GPU. The whole bundle is embedded in the gcx binary via include_bytes!, so there is no runtime dependency beyond a browser.

Features:

  • GPGPU force layout — clusters form naturally on first paint, smooth at 60fps even on thousands of nodes
  • Three-pane shell — FilterRail (left) · Cosmograph canvas (center) · Inspector (right) · StatusBar (bottom)
  • Density modes in the header: Focused (only semantically connected nodes), Public API (only pub symbols), Full (all)
  • Cmd+K search palette — fuzzy match on name and qualified_name, ↑/↓/Enter keyboard navigation, click zooms-to-node
  • Inspector tabs — local Callers/Callees/Uses (computed client-side from the live graph), plus a Deep Callers tab backed by MCP find_callers_deep with risk scoring (LOW / MEDIUM / HIGH / CRITICAL)
  • Branch diff overlay — pick a branch from the header dropdown; added nodes glow emerald, removed nodes glow red, with a live legend
  • NodeKind + EdgeKind filter toggles in the left rail, with per-kind counts
  • Floating canvas controls — zoom in/out, fit, focus selected, play/pause simulation
  • Catppuccin dark theme with custom Tailwind v4 design tokens (--color-void, --color-accent, etc.)
  • Editor links — clicking a node opens it in VS Code/Cursor/IDEA via file:line URI

gcx blast-radius

Show which callers are affected by changes between two branches. Powers the PR comment bot.

gcx blast-radius --base main --head feat/auth
gcx blast-radius --base main --head feat/auth --depth 3
gcx blast-radius --base main --head feat/auth --format github-comment
gcx blast-radius --base main --head feat/auth --format json

Example output (--format text):

Blast Radius Report
────────────────────────────────────────────────────
  feat/auth → main
  Changed: 2  |  Affected: 8  |  Risk: MEDIUM
────────────────────────────────────────────────────
Changed nodes:
  function    validate_token               src/auth.rs:23
  method      build_claims                 src/auth.rs:54

Affected callers:
  [hop 1]  function    handle_request      src/handler.rs:8
  [hop 1]  function    middleware_chain    src/middleware.rs:3
  [hop 2]  function    router              src/main.rs:12
  ...

gcx export

Generates .gitcortex/context.md — a readable Markdown codebase map organized by file with hierarchical struct→method containment. Once generated, the git hook keeps it fresh after every commit.

gcx export                          # writes .gitcortex/context.md (Markdown map)
gcx export --branch feat/auth
gcx export --format json > graph.json   # committable JSON: symbols + edges, joinable by id
gcx export --claude-md --top 40     # upsert top-N symbols into CLAUDE.md
  • --format json — emits { branch, sha, symbols[], edges[] } to stdout. Each symbol carries id, name, qualified_name, kind, file, line, visibility; edges reference symbol ids. Commit it, diff it in PRs, or consume it in CI without the binary or the embedded DB.
  • --claude-md — upserts a compact, centrality-ranked symbol table into CLAUDE.md between <!-- gcx:symbols start/end --> markers (idempotent). Assistants get the most-referenced symbols (name → file:line) pre-loaded with zero tool calls, with a hint to fall back to the MCP tools for anything not listed.

Example output:

# Codebase Map

> Branch: `main` · 312 definitions · SHA: `abc1234`

## src/auth.rs

- `pub struct AuthConfig` :5
  - `pub fn from_env` :10
  - `pub fn is_valid` :20
- `pub async fn validate_token` :30

## src/handler.rs

- `pub fn handle_request` :8

Commit .gitcortex/context.md to give teammates (and Claude) instant codebase context without an MCP server.

gcx status

Show node and edge counts for the current branch.

gcx status
gcx status --branch feat/auth

branch:     main
last sha:   abc1234...
nodes:      312
  function     80
  method       69
  struct       22
  ...
edges:      847
  calls        514
  contains     246
  ...

gcx clean

Wipe the graph store for this repo so the next gcx init or commit triggers a full re-index.

gcx clean

gcx doctor

Diagnose setup issues: hooks installed, MCP registered, store accessible, index current.

gcx doctor

Example output:

gcx doctor

  [ok] gcx v0.3.0 on PATH (/usr/local/bin/gcx)
  [ok] git repository detected
  [ok] post-commit hook installed
  [ok] post-merge hook installed
  [ok] post-rewrite hook installed
  [ok] post-checkout hook installed
  [ok] graph store accessible  (1 842 nodes, 4 217 edges on main)
  [ok] index is current  (HEAD abc1234)
  [ok] MCP registered  (Claude Code)
  [--] MCP not configured for Cursor  (run: gcx init --editor cursor)

All checks passed.

gcx update

Check for a newer release and print the right update command for your install method.

gcx update

gcx update

  current version:  0.3.0
  latest version:   0.3.0
  you are up to date.

  To update (cargo):
    cargo install gitcortex

CI / PR blast radius bot

gcx init --ci

This writes .github/workflows/gcx-blast-radius.yml. On every pull request it runs gcx blast-radius and posts the result as a sticky PR comment using the github-comment format.

MCP integration

gcx init registers the MCP server in ~/.claude.json — no per-project config needed. The server is available in every Claude Code session on this machine automatically.

Available MCP tools

Tool Description
lookup_symbol Find all nodes matching a name across the codebase
find_callers All functions that call a given function (backward trace)
find_callees All functions called by a given function (forward trace, configurable depth)
list_definitions All definitions in a source file ordered by line
find_implementors All structs/classes that implement a trait or interface
trace_path Every call path between two symbols (up to 6 hops)
list_symbols_in_range Symbols whose span overlaps a file + line range
find_unused_symbols Symbols with zero callers — dead code candidates
get_subgraph All nodes + edges within N hops of a seed symbol (in/out/both)
branch_diff_graph Nodes added or removed between two branches
detect_changes Changed symbols + blast radius vs a base branch
symbol_context Callers, callees, and used-by for a symbol

All tools accept an optional branch parameter. Defaults to the branch active when gcx serve was started (auto-detected from git symbolic-ref HEAD).

MCP prompts

Prompt What it does
detect_impact Pre-commit impact analysis — maps a list of changed files to affected callers and scores risk LOW / MEDIUM / HIGH / CRITICAL
generate_map Architecture diagram — produces a Mermaid module map, key types table, and core execution flows

Prompts are multi-step workflows your AI assistant executes automatically using the tools above. In Claude Code, invoke them via the prompt picker or with /mcp__gitcortex__detect_impact.

Claude Code slash commands

gcx init installs four slash commands into .claude/commands/gcx/ that are immediately available in Claude Code:

Command What it does
/gcx-lookup <name> Find all definitions matching a name
/gcx-callers <name> Find all callers of a function
/gcx-file <path> List all definitions in a file
/gcx-blast-radius Show blast radius of changes vs main

Configuration

.gitcortex/config.toml

Committed to the repo and shared with your team.

[index]
languages = ["rust", "typescript", "python", "go"]
max_file_size_kb = 500

[lld]
enabled = false         # pass-2 LLD annotation (v0.2)

[store]
backend = "local"       # local only in v0.1; remote backend planned

.gitcortex/ignore

.gitignore-syntax patterns for files to exclude from indexing.

target/
build/
**/*.generated.rs
**/*.pb.rs

Graph schema

Node kinds

Kind Languages Description
File all Source file
Module all mod foo { }, Python module, Go package
Struct Rust/Go/TS/Java struct Foo, class Foo
Enum all enum Bar
Trait Rust/Python trait Baz, abstract base class
Interface TS/Go/Java/Python interface Foo, structural interface, Protocol subclass
TypeAlias Rust/TS/Python type Alias = ...
Function all Free-standing function
Method all Method inside a class / impl block
Constant all const / static
Macro Rust macro_rules! or proc-macro
Property TS/Python Class property, @property
Annotation Java @interface annotation type
EnumMember all Variant inside an enum

Edge kinds

Kind Description
Contains Parent–child: File→Module, Struct→Method
Calls Resolved call site: Function→Function
Implements impl Trait for Struct, class implements interface
Inherits extends / embedded struct / sealed permits
Uses Type appears as parameter or return type
Imports use path::to::Thing, import
Throws Java throws clause → exception type
Annotated Node decorated by #[attr], @decorator, @annotation

Python indexing detail

The Python parser fully resolves the following patterns:

Pattern NodeKind emitted Metadata set
class Foo(Protocol): Interface is_abstract = true
class Foo: / @dataclass class Foo: Struct —
@property def bar(self): Property is_property = true
@staticmethod def fn(): Method is_static = true
@classmethod def fn(cls): Method is_static = true
async def fn(): Function / Method is_async = true
def fn(): yield … Function is_generator = true
async def fn(): yield … Function is_async = true, is_generator = true
UPPER_SNAKE_CASE = … at module level Constant —
Nested class Inner: inside class Outer: Struct Contains edge from Outer

Node metadata flags

Every node carries: loc, visibility (Pub / PubCrate / Private), is_async, is_unsafe, is_static, is_abstract, is_final, is_const, is_property, is_generator, and generic_bounds.

Data storage

The graph database is stored locally and never committed:

~/.local/share/gitcortex/{repo_id}/
    graph.kuzu       # KuzuDB database (all branches, namespaced by table prefix)
    main.sha         # last indexed SHA for branch "main"
    feat__auth.sha   # last indexed SHA for branch "feat/auth"

Architecture

flowchart TD
    subgraph repo["Your Repository"]
        hooks["git hooks\npost-commit · post-merge · post-rewrite · post-checkout"]
        files["Source Files — .rs · .ts · .py · .go"]
    end

    subgraph indexer["gitcortex-indexer"]
        differ["git2 differ\nchanged files only"]
        parsers["tree-sitter parsers\nRust · TypeScript · Python · Go"]
        differ --> parsers
    end

    kuzu[("KuzuDB\nbranch-namespaced\ngraph store")]

    subgraph gcx["gitcortex-mcp  ·  gcx"]
        server["MCP server\nlookup_symbol · find_callers\nlist_definitions · branch_diff_graph"]
        blast["gcx blast-radius\nrisk scoring · PR comment"]
        viz["gcx viz\nbrowser graph · DOT export"]
    end

    claude["Claude Code\nMCP tools · slash commands · skills"]
    gh["GitHub Actions\nsticky PR blast-radius comment"]

    hooks -->|"gcx hook — incremental diff"| differ
    files --> differ
    parsers -->|"GraphDiff\nnodes + edges"| kuzu
    kuzu --> server
    kuzu --> blast
    kuzu --> viz
    server --> claude
    blast --> gh

The GraphStore trait is the extensibility boundary — the local KuzuDB backend can be swapped for a remote backend without touching the indexer or MCP layer.

Limitations & roadmap

GitCortex builds a syntactic graph from tree-sitter ASTs. That's deliberate — it keeps indexing fast and dependency-free — but it sets the boundaries below. Contributions toward any of these are welcome.

Known gaps

  • No type inference. Call resolution matches on names, not resolved types. Calls to very common names (get, save, __init__) are left unlinked rather than fanned out to every same-named definition.
  • Go interface satisfaction not inferred. Go satisfies interfaces structurally (no implements keyword), so find-implementors on a Go interface returns nothing. Embedding (inherits) is captured.
  • Java member annotations & fields not modeled. @Override / @SerializedName on members and static final fields don't yet produce nodes/edges, so annotation-target and field-level queries are incomplete.
  • Go type-declaration signatures render without the leading type keyword and struct/interface body (the type name + kind are correct).
  • Windows is unsupported — KuzuDB 0.11.3 (upstream archived) doesn't link under MSVC. macOS (arm64/x86_64) and Linux (x86_64/aarch64) ship pre-built binaries.

Roadmap

  • Pass-2 LLD annotation (SOLID hints, design patterns, code smells, cyclomatic complexity) — schema is already in place.
  • Optional semantic search over DefinitionText (signatures + docstrings are already captured).
  • Remote GraphStore backend for team-shared graphs (the trait boundary exists today).
  • Deeper Java/Go modeling (fields, annotations, structural interface satisfaction).

See open issues for the live list.

Contributing

Contributions are welcome — bug reports, language-coverage improvements, new MCP tools, docs.

  • Start here: CONTRIBUTING.md — dev setup, build, test, and PR workflow.
  • Conduct: CODE_OF_CONDUCT.md.
  • Test your changes against real repos: scripts/lang-smoke.sh <git-url> <symbol> clones a repo, indexes it, exercises every query + the MCP round-trip, and prints PASS/FAIL with metrics.
  • Releasing: RELEASING.md.

Good first issues: add a LanguageParser for a new language, deepen an existing parser (see the coverage matrix), or add an MCP tool.

License

MIT © GitCortex contributors.