Gitcortex

https://docs.rs/gitcortex/0.6.0/
Admin
Gitcortex is a Git-aware code knowledge graph that performs incremental AST indexing on every...
Tokens:6,663
Snippets:89
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install and Initialize GitCortex

Source: https://docs.rs/gitcortex

Commands to install the tool and initialize indexing for a repository.

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

--------------------------------

### Start MCP Server

Source: https://docs.rs/gitcortex

Launches the MCP server for assistant integration.

```bash
gcx serve             # full MCP surface
gcx serve --compact   # single-dispatch `gcx` tool only; recommended for Codex/token-sensitive agents
```

--------------------------------

### Install via one-line shell script

Source: https://docs.rs/gitcortex

Use the provided shell script to automatically download and install the latest version.

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

--------------------------------

### Diagnose setup issues

Source: https://docs.rs/gitcortex

Verifies hooks, MCP registration, and index status.

```bash
gcx doctor
```

--------------------------------

### Install via gcx curl installer

Source: https://docs.rs/gitcortex

Alternative shell installer for macOS and Linux systems.

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

--------------------------------

### Install via Python package managers

Source: https://docs.rs/gitcortex

Use pip, pipx, or uv to install GitCortex without requiring a Rust toolchain.

```bash
pip install gitcortex
# or (isolated install, preferred for CLI tools)
pipx install gitcortex
# or
uv tool install gitcortex
```

--------------------------------

### Install via Node.js package managers

Source: https://docs.rs/gitcortex

Use npm, pnpm, or yarn to install GitCortex globally.

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

--------------------------------

### View Initialization Output

Source: https://docs.rs/gitcortex

Example output generated after running the gcx init command.

```text
GitCortex initialised  (820ms)
  Graph:     2 141 nodes | 5 328 edges
  Hooks:     4 git hooks installed
  Editors:   Codex, Cursor, Claude Code (auto-detected)
  Universal: .gitcortex/AGENT_GUIDE.md, .gitcortex/ignore
```

--------------------------------

### Install pre-commit hook

Source: https://docs.rs/gitcortex

Run this command after cloning to enable automatic formatting and linting before commits.

```bash
cp hooks/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
```

--------------------------------

### Install via Cargo

Source: https://docs.rs/gitcortex

Install directly from crates.io using the Rust package manager.

```bash
cargo install gitcortex
```

--------------------------------

### gcx init

Source: https://docs.rs/gitcortex

Initializes the GitCortex environment by installing git hooks, performing an initial index, and configuring supported editors.

```APIDOC
## gcx init

### Description
Installs four git hooks, runs the initial full index, registers the MCP server in the detected editor(s), and writes a universal context file.

### Usage
`gcx init [options]`

### Options
- **--editor** (string) - Optional - Target editor (codex, claude, cursor, windsurf, copilot, antigravity, or all).
- **--ci** (flag) - Optional - Writes CI workflow configuration.
```

--------------------------------

### gcx serve

Source: https://docs.rs/gitcortex

Starts the MCP server on stdio to provide AI assistants with access to the knowledge graph.

```APIDOC
## gcx serve

### Description
Starts the MCP server on stdio. This should be configured in an assistant's MCP config to enable knowledge graph access.

### Usage
`gcx serve [options]`

### Options
- **--compact** (flag) - Optional - Enables single-dispatch gcx tool only; recommended for token-sensitive agents.
```

--------------------------------

### gcx doctor

Source: https://docs.rs/gitcortex

Diagnoses setup issues within the repository.

```APIDOC
## gcx doctor

### Description
Checks for proper installation of git hooks, MCP registration, graph store accessibility, and index currency.
```

--------------------------------

### Initialize with Specific Options

Source: https://docs.rs/gitcortex

Configures editor integration and CI workflows during initialization.

```bash
gcx init                      # auto-detects editor(s) from environment
gcx init --editor codex       # explicit target: codex, 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
```

--------------------------------

### Initialize GitCortex

Source: https://docs.rs/gitcortex

Sets up git hooks and indexes the current repository.

```bash
cd your-repo
gcx init
```

--------------------------------

### Build from source

Source: https://docs.rs/gitcortex

Clone the repository and compile the project using cargo.

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

--------------------------------

### Download direct binaries for macOS and Linux

Source: https://docs.rs/gitcortex

Download and move the gcx binary to /usr/local/bin for system-wide access.

```bash
# macOS Apple Silicon (M1/M2/M3)
curl -LO https://github.com/bharath03-a/GitCortex/releases/latest/download/gitcortex-aarch64-apple-darwin.tar.xz
tar -xf gitcortex-aarch64-apple-darwin.tar.xz
sudo mv gcx /usr/local/bin/

# macOS Intel
curl -LO https://github.com/bharath03-a/GitCortex/releases/latest/download/gitcortex-x86_64-apple-darwin.tar.xz
tar -xf gitcortex-x86_64-apple-darwin.tar.xz
sudo mv gcx /usr/local/bin/

# Linux x86_64
curl -LO https://github.com/bharath03-a/GitCortex/releases/latest/download/gitcortex-x86_64-unknown-linux-gnu.tar.xz
tar -xf gitcortex-x86_64-unknown-linux-gnu.tar.xz
sudo mv gcx /usr/local/bin/

# Linux ARM64
curl -LO https://github.com/bharath03-a/GitCortex/releases/latest/download/gitcortex-aarch64-unknown-linux-gnu.tar.xz
tar -xf gitcortex-aarch64-unknown-linux-gnu.tar.xz
sudo mv gcx /usr/local/bin/
```

--------------------------------

### gcx init --ci

Source: https://docs.rs/gitcortex

Configures CI/CD integration for PR analysis.

```APIDOC
## gcx init --ci

### Description
Writes a .github/workflows/gcx-blast-radius.yml file to the repository to enable automated PR blast radius analysis.
```

--------------------------------

### gcx init

Source: https://docs.rs/gitcortex

Registers the GitCortex MCP server for the detected editor.

```APIDOC
## gcx init

### Description
Registers the MCP server for the detected editor(s). Use the --editor flag to specify a target.

### Usage
`gcx init --editor <target>`

### Parameters
- **--editor** (string) - Optional - The target editor to register (e.g., 'codex', 'claude', 'all').
```

--------------------------------

### Visualize Knowledge Graph

Source: https://docs.rs/gitcortex

Commands to launch the interactive WebGL visualization or export the graph to various formats.

```bash
gcx viz                                # default: WebGL Cosmograph UI on port 5678
gcx viz --port 9000                    # custom port
gcx viz --branch feat/auth             # visualise a different branch
gcx viz --format html > graph.html     # self-contained vis-network HTML, open offline
gcx viz --format svg  > graph.svg      # static SVG with kind-grouped concentric layout
gcx viz --format dot  > graph.dot      # Graphviz DOT (pipe to `dot -Tsvg ...`)
gcx viz --format graphml > graph.graphml   # importable by Gephi, yEd, Cytoscape
gcx viz --format cypher > import.cypher    # Neo4j bulk CREATE statements
```

--------------------------------

### Run GitCortex Benchmarks

Source: https://docs.rs/gitcortex

Commands to build the project and execute various benchmark sweeps and individual repository tests.

```bash
cargo build --release --bin gcx
# Codex compact-MCP sweep (5 languages, 4 questions)
bash docs/benchmarks/codex-sweep.sh gpt-5.4-mini 4
# Claude sweep (haiku, release-gate benchmark)
bash docs/benchmarks/real-sweep.sh
# Single Codex repo
bash docs/benchmarks/codex-harness.sh \
    https://github.com/BurntSushi/ripgrep \
    /tmp/ripgrep-codex.json gpt-5.4-mini 4
# Single Claude repo
bash docs/benchmarks/real-harness.sh \
    https://github.com/BurntSushi/ripgrep \
    /tmp/ripgrep.json claude-haiku-4-5-20251001 4
# Render HTML reports from existing JSON
python3 docs/benchmarks/real-report.py docs/benchmarks/codex-report-data \
    -o docs/benchmarks/codex-report.html
python3 docs/benchmarks/real-report.py
```

--------------------------------

### Initialize GitCortex MCP Server

Source: https://docs.rs/gitcortex

Registers the MCP server for detected editors. Use the --editor flag to specify a target.

```bash
gcx init --editor codex
gcx init --editor claude
gcx init --editor all
```

--------------------------------

### Run language smoke tests

Source: https://docs.rs/gitcortex

Use this script to verify changes against real repositories by indexing and running queries.

```bash
scripts/lang-smoke.sh <git-url> <symbol>
```

--------------------------------

### Initialize CI blast radius bot

Source: https://docs.rs/gitcortex

Writes a GitHub Actions workflow file to post codebase impact analysis on pull requests.

```bash
gcx init --ci
```

--------------------------------

### GitCortex System Architecture

Source: https://docs.rs/gitcortex

Mermaid diagram illustrating the flow from git hooks and source files through the indexer to the KuzuDB store and MCP interfaces.

```mermaid
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

    assistants["AI assistants\nCodex compact MCP · Claude Code\nCursor · Windsurf · Copilot"]
    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 --> assistants
    blast --> gh
```

--------------------------------

### Configure GitCortex MCP Server

Source: https://docs.rs/gitcortex

Configuration block for the GitCortex MCP server, typically used in editor settings.

```toml
[mcp_servers.gitcortex]
command = "gcx"
args = ["serve", "--compact"]
startup_timeout_sec = 30
```

--------------------------------

### Query Knowledge Graph

Source: https://docs.rs/gitcortex

Performs manual inspection of the codebase using symbol lookups, call graph analysis, and discovery tools.

```bash
# 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 query find-god-nodes --min-in-degree 5   # high-fan-in hub symbols
gcx query find-clusters --min-cluster-size 3 # code communities via label propagation
```

--------------------------------

### Configure GitCortex ignore patterns

Source: https://docs.rs/gitcortex

Defines file patterns to exclude from indexing. Commit this file to version control to share exclusions across the team.

```text
target/
build/
dist/
vendor/
**/*.generated.rs
**/*.pb.rs
.fastembed_cache/
```

--------------------------------

### Claude Code Slash Commands

Source: https://docs.rs/gitcortex

Commands available in Claude Code after running gcx init.

```APIDOC
## Claude Code Slash Commands

### Description
Commands installed into .claude/commands/gcx/ for direct invocation in Claude Code.

### Commands
- **/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.
```

--------------------------------

### GitCortex Local Storage Structure

Source: https://docs.rs/gitcortex

The local directory structure for KuzuDB files, branch-specific SHA tracking, and semantic embeddings.

```text
~/.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"
    embeddings_main.bin   # semantic vector index for branch "main"

~/.local/share/gitcortex/models/
    # fastembed model weights (~23 MB, downloaded once, shared across all repos)
```

--------------------------------

### Export codebase context

Source: https://docs.rs/gitcortex

Generates a Markdown codebase map or JSON graph representation. Use the --claude-md flag to inject symbol tables into CLAUDE.md.

```bash
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
```

--------------------------------

### gcx query

Source: https://docs.rs/gitcortex

Performs one-shot CLI queries for manual inspection of the code graph.

```APIDOC
## gcx query

### Description
Executes queries against the indexed code graph. The same surface is exposed to AI assistants as MCP tools.

### Commands
- **lookup-symbol** [name] - Locate a specific symbol.
- **search** [query] --limit [n] - Ranked fuzzy match search.
- **list-definitions** [path] - List definitions in a file or directory.
- **find-callers** [symbol] --branch [name] --depth [n] - Find callers of a symbol.
- **find-callees** [symbol] - Find callees of a symbol.
- **trace-path** [start] [end] - Trace path between two symbols.
- **symbol-context** [symbol] - Get a 360-degree view of a symbol.
- **wiki** [symbol] - Generate a markdown wiki page for a symbol.
- **tour** --limit [n] --seed [name] - Perform a centrality-ranked or BFS-walk tour.
- **find-god-nodes** --min-in-degree [n] - Find high-fan-in hub symbols.
- **find-clusters** --min-cluster-size [n] - Find code communities.
```

--------------------------------

### Configure ANSI Color Output

Source: https://docs.rs/gitcortex

Controls colorized output for gcx subcommands using the --color flag.

```bash
gcx --color auto    query lookup-symbol Foo   # default: colour only when stdout is a TTY
gcx --color always  query find-callers bar    # force colour (useful in pipes that handle ANSI)
gcx --color never   query symbol-context baz  # plain text, for scripts and CI
```

--------------------------------

### Update GitCortex

Source: https://docs.rs/gitcortex

Checks for newer releases and provides the appropriate update command.

```bash
gcx update
```

--------------------------------

### gcx update

Source: https://docs.rs/gitcortex

Checks for available updates for the GitCortex CLI.

```APIDOC
## gcx update

### Description
Compares the current version against the latest release and provides the appropriate update command.
```

--------------------------------

### Check repository status

Source: https://docs.rs/gitcortex

Displays node and edge counts for the current branch or a specified branch.

```bash
gcx status
gcx status --branch feat/auth
```

--------------------------------

### gcx export

Source: https://docs.rs/gitcortex

Generates a codebase map or exports graph data. It creates a .gitcortex/context.md file by default, which is kept updated by git hooks.

```APIDOC
## gcx export

### Description
Generates a readable Markdown codebase map or exports structured JSON data. The map is organized by file with hierarchical struct and method containment.

### Usage
`gcx export [options]`

### Options
- **--branch** (string) - Optional - Specifies the branch to export.
- **--format** (string) - Optional - Set to 'json' to output symbol and edge data to stdout.
- **--claude-md** (flag) - Optional - Upserts a centrality-ranked symbol table into CLAUDE.md.
- **--top** (integer) - Optional - Limits the number of symbols exported when using --claude-md.
```

--------------------------------

### gcx clean

Source: https://docs.rs/gitcortex

Wipes the local graph store for the repository.

```APIDOC
## gcx clean

### Description
Removes the graph store for the current repository, forcing a full re-index on the next initialization or commit.
```

--------------------------------

### Manage Git Hooks

Source: https://docs.rs/gitcortex

Triggers internal hook logic, typically handled automatically by git events.

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

--------------------------------

### gcx status

Source: https://docs.rs/gitcortex

Displays the current node and edge counts for the repository graph.

```APIDOC
## gcx status

### Description
Shows the current state of the graph store, including node counts by type and edge counts by relationship type.

### Usage
`gcx status [options]`

### Options
- **--branch** (string) - Optional - Specifies the branch to check.
```

--------------------------------

### Calculate Blast Radius

Source: https://docs.rs/gitcortex

Analyze the impact of changes between two branches to identify affected callers.

```bash
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
```

```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
  ...
```

--------------------------------

### Clean graph store

Source: https://docs.rs/gitcortex

Removes the local graph store to force a full re-index on the next operation.

```bash
gcx clean
```
Tokens:
Raw