CodraGraph

Graph-powered code intelligence for AI agents. Index any codebase into a knowledge graph, then query it via MCP or CLI.

Works with Cursor, Claude Code, Codex, Windsurf, Cline, OpenCode, and any MCP-compatible tool.

Why?

AI coding tools don't understand your codebase structure. They edit a function without knowing 47 other functions depend on it. CodraGraph fixes this by precomputing every dependency, call chain, and relationship into a queryable graph.

Three commands to give your AI agent full codebase awareness.

Quick Start

# Index your repo (run from repo root)
npx @codragraph/cli analyze

That's it. This indexes the codebase, installs agent skills, registers Claude Code hooks, and creates AGENTS.md / CLAUDE.md context files — all in one command.

To configure MCP for your editor, run npx @codragraph/cli setup once — or set it up manually below.

codragraph setup auto-detects your editors and writes the correct global MCP config. You only need to run it once.

Editor Support

| Editor | MCP | Skills | Hooks (auto-augment) | Support | |--------|-----|--------|---------------------|---------| | Claude Code | Yes | Yes | Yes (PreToolUse) | Full | | Cursor | Yes | Yes | — | MCP + Skills | | Codex | Yes | Yes | — | MCP + Skills | | Windsurf | Yes | — | — | MCP | | OpenCode | Yes | Yes | — | MCP + Skills |

Claude Code gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context.

Community Integrations

| Agent | Install | Source | |-------|---------|--------| | pi | pi install npm:pi-codragraph | pi-codragraph |

MCP Setup (manual)

If you prefer to configure manually instead of using codragraph setup:

Claude Code (full support — MCP + skills + hooks)

# macOS / Linux
claude mcp add codragraph -- npx -y @codragraph/cli@latest mcp

# Windows
claude mcp add codragraph -- cmd /c npx -y @codragraph/cli@latest mcp

Codex (full support — MCP + skills)

codex mcp add codragraph -- npx -y @codragraph/cli@latest mcp

Cursor / Windsurf

Add to ~/.cursor/mcp.json (global — works for all projects):

{
  "mcpServers": {
    "codragraph": {
      "command": "npx",
      "args": ["-y", "@codragraph/cli@latest", "mcp"]
    }
  }
}

OpenCode

Add to ~/.config/opencode/config.json:

{
  "mcp": {
    "codragraph": {
      "command": "npx",
      "args": ["-y", "@codragraph/cli@latest", "mcp"]
    }
  }
}

How It Works

CodraGraph builds a complete knowledge graph of your codebase through a multi-phase indexing pipeline:

1. Structure — Walks the file tree and maps folder/file relationships
2. Parsing — Extracts functions, classes, methods, and interfaces using Tree-sitter ASTs
3. Resolution — Resolves imports and function calls across files with language-aware logic
   • Field & Property Type Resolution — Tracks field types across classes and interfaces for deep chain resolution (e.g., user.address.city.getName())
   • Return-Type-Aware Variable Binding — Infers variable types from function return types, enabling accurate call-result binding
4. Clustering — Groups related symbols into functional communities
5. Processes — Traces execution flows from entry points through call chains
6. Search — Builds hybrid search indexes for fast retrieval

The result is a LadybugDB graph database stored locally in .codragraph/ with full-text search and semantic embeddings.

MCP Tools

Your AI agent gets these tools automatically:

| Tool | What It Does | repo Param | |------|-------------|--------------| | list_repos | Discover all indexed repositories | — | | query | Process-grouped hybrid search (BM25 + semantic + RRF) | Optional | | context | 360-degree symbol view — categorized refs, process participation | Optional | | impact | Blast radius analysis with depth grouping and confidence | Optional | | detect_changes | Git-diff impact — maps changed lines to affected processes | Optional | | rename | Multi-file coordinated rename with graph + text search | Optional | | cypher | Raw Cypher graph queries | Optional |

With one indexed repo, the repo param is optional. With multiple, specify which: query({query: "auth", repo: "my-app"}).

MCP Resources

| Resource | Purpose | |----------|---------| | codragraph://repos | List all indexed repositories (read first) | | codragraph://repo/{name}/context | Codebase stats, staleness check, and available tools | | codragraph://repo/{name}/clusters | All functional clusters with cohesion scores | | codragraph://repo/{name}/cluster/{name} | Cluster members and details | | codragraph://repo/{name}/processes | All execution flows | | codragraph://repo/{name}/process/{name} | Full process trace with steps | | codragraph://repo/{name}/schema | Graph schema for Cypher queries |

MCP Prompts

| Prompt | What It Does | |--------|-------------| | detect_impact | Pre-commit change analysis — scope, affected processes, risk level | | generate_map | Architecture documentation from the knowledge graph with mermaid diagrams |

CLI Commands

codragraph setup                   # Configure MCP for your editors (one-time)
codragraph analyze [path]          # Index a repository (or update stale index)
codragraph analyze --force         # Force full re-index
codragraph analyze --embeddings    # Enable embedding generation (slower, better search)
codragraph analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md codragraph section edits
codragraph analyze --verbose       # Log skipped files when parsers are unavailable
codragraph analyze --max-file-size 1024  # Skip files larger than N KB (default: 512, cap: 32768)
codragraph analyze --compress brotli  # Per-row body compression. Also: zstd, none.
codragraph profile-heap [path]     # Run analyze with v8 heap-snapshot instrumentation
codragraph profile-heap --no-summary  # Same, but skip the post-run RSS / heapUsed table
codragraph mcp                     # Start MCP server (stdio) — serves all indexed repos
codragraph serve                   # Start local HTTP server (multi-repo) for web UI
codragraph index                   # Register an existing .codragraph/ folder into the global registry
codragraph list                    # List all indexed repositories
codragraph status                  # Show index status for current repo
codragraph clean                   # Delete index for current repo
codragraph clean --all --force     # Delete all indexes
codragraph wiki [path]             # Generate LLM-powered docs from knowledge graph
codragraph wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)

# Repository groups (multi-repo / monorepo service tracking)
codragraph group create <name>                                   # Create a repository group
codragraph group add <group> <groupPath> <registryName>          # Add a repo to a group. <groupPath> is a hierarchy path (e.g. hr/hiring/backend); <registryName> is the repo's name from the registry (see `codragraph list`)
codragraph group remove <group> <groupPath>                      # Remove a repo from a group by its hierarchy path
codragraph group list [name]                                     # List groups, or show one group's config
codragraph group sync <name>                                     # Extract contracts and match across repos/services
codragraph group contracts <name>  # Inspect extracted contracts and cross-links
codragraph group query <name> <q>  # Search execution flows across all repos in a group
codragraph group status <name>     # Check staleness of repos in a group

Remote Embeddings

Set these env vars to use a remote OpenAI-compatible /v1/embeddings endpoint instead of the local model:

export CODRAGRAPH_EMBEDDING_URL=http://your-server:8080/v1
export CODRAGRAPH_EMBEDDING_MODEL=BAAI/bge-large-en-v1.5
export CODRAGRAPH_EMBEDDING_DIMS=1024          # optional, default 384
export CODRAGRAPH_EMBEDDING_API_KEY=your-key   # optional, default: "unused"
codragraph analyze . --embeddings

Works with Infinity, vLLM, TEI, llama.cpp, Ollama, LM Studio, or OpenAI. When unset, local embeddings are used unchanged.

Multi-Repo Support

CodraGraph supports indexing multiple repositories. Each codragraph analyze registers the repo in a global registry (~/.codragraph/registry.json). The MCP server serves all indexed repos automatically.

Supported Languages

TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP, Kotlin, Swift, Ruby

Language Feature Matrix

| Language | Imports | Named Bindings | Exports | Heritage | Type Annotations | Constructor Inference | Config | Frameworks | Entry Points | |----------|---------|----------------|---------|----------|-----------------|---------------------|--------|------------|-------------| | TypeScript | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | JavaScript | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ | | Python | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Java | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | | Kotlin | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | | C# | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Go | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Rust | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | | PHP | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | | Ruby | ✓ | — | ✓ | ✓ | — | ✓ | — | ✓ | ✓ | | Swift | — | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | C | — | — | ✓ | — | ✓ | ✓ | — | ✓ | ✓ | | C++ | — | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |

Imports — cross-file import resolution · Named Bindings — import { X as Y } / re-export tracking · Exports — public/exported symbol detection · Heritage — class inheritance, interfaces, mixins · Type Annotations — explicit type extraction for receiver resolution · Constructor Inference — infer receiver type from constructor calls (self/this resolution included for all languages) · Config — language toolchain config parsing (tsconfig, go.mod, etc.) · Frameworks — AST-based framework pattern detection · Entry Points — entry point scoring heuristics

Agent Skills

CodraGraph ships with skill files that teach AI agents how to use the tools effectively:

• Exploring — Navigate unfamiliar code using the knowledge graph
• Debugging — Trace bugs through call chains
• Impact Analysis — Analyze blast radius before changes
• Refactoring — Plan safe refactors using dependency mapping

Installed automatically by both codragraph analyze (per-repo) and codragraph setup (global).

Requirements

• Node.js >= 18
• Git repository (uses git for commit tracking)

Release candidates

Stable releases publish to the default latest dist-tag. When a pull request with non-documentation changes merges into main, an automated workflow also publishes a prerelease build under the rc dist-tag, so early adopters can try in-flight fixes without waiting for the next stable cut. (Docs-only merges are skipped.)

# Try the latest release candidate (pre-stable — may change at any time)
npm install -g @codragraph/cli@rc
# — or —
npx @codragraph/cli@rc analyze

Release-candidate versions follow the standard semver prerelease format X.Y.Z-rc.N, where X.Y.Z is the next stable target (bumped from the current latest by patch by default; minor or major when kicking off a bigger cycle) and N increments per published rc. Example sequence: 1.6.2-rc.1, 1.6.2-rc.2, …, then once 1.6.2 ships stable, 1.6.3-rc.1. Stable latest is unaffected.

Troubleshooting

Cannot destructure property 'package' of 'node.target' as it is null

This crash was caused by a dependency URL format that is incompatible with certain npm/arborist versions (npm/cli#8126). It is fixed in codragraph v1.6.2+. Upgrade to the latest version:

npx @codragraph/cli@latest analyze          # always uses the newest release
# — or —
npm install -g @codragraph/cli@latest       # upgrade a global install

If you still hit npm install issues after upgrading, these generic workarounds may help:

npm install -g npm@latest            # update npm itself
npm cache clean --force              # clear a possibly corrupt cache

Installation fails with native module errors

Some optional language grammars (Dart, Kotlin, Swift) require native compilation. If they fail, CodraGraph still works — those languages will be skipped.

If npm install -g @codragraph/cli fails on native modules:

# Ensure build tools are available (Linux/macOS)
# Ubuntu/Debian: sudo apt install python3 make g++
# macOS: xcode-select --install

# Retry installation
npm install -g @codragraph/cli

Analysis runs out of memory

For very large repositories:

# Increase Node.js heap size
NODE_OPTIONS="--max-old-space-size=16384" npx @codragraph/cli analyze

# Exclude large directories
echo "vendor/" >> .codragraphignore
echo "dist/" >> .codragraphignore

If you want to know which phase is dragging the heap up before deciding what to mitigate, run codragraph profile-heap. It writes a v8 heap snapshot at every phase boundary plus a JSONL timeline of process.memoryUsage() and prints a per-phase RSS / heapUsed table:

codragraph profile-heap                       # writes .codragraph/heap-profiles/
# → load any .heapsnapshot in Chrome DevTools → Memory → Load

Each snapshot is 100–500 MB, so the command is opt-in only. The JSONL timeline is small enough to share for triage even when the snapshots are too big.

Index size — opt-in per-row compression

For repos where .codragraph/cgdb itself has grown large:

codragraph analyze --compress brotli   # Node ≥ 18, brotli quality 6
codragraph analyze --compress zstd     # Node ≥ 22.15, zstd level 3
codragraph analyze --compress none     # explicit default

--compress routes every node-row content field through the matching encoder before it's written to the CSV / cgdb; readers decode transparently via the per-row contentEncoding tag. With the flag unset, the on-disk layout is byte-identical to pre-1.8 indexes. Pre-1.8 indexes auto-trigger a full re-analyze the first time a 1.8+ CLI runs against them (one-time cost, surfaced in the analyze log).

Large files are being skipped

By default the walker skips files larger than 512 KB (see log line Skipped N large files (>512KB)). Raise the threshold via either the CLI flag or the environment variable — both accept a value in KB:

# CLI flag (takes precedence over the env var)
npx @codragraph/cli analyze --max-file-size 2048     # skip only files > 2 MB

# Environment variable (persists across commands)
export CODRAGRAPH_MAX_FILE_SIZE=2048
npx @codragraph/cli analyze

Values above 32768 KB (32 MB) are clamped to the tree-sitter parser ceiling; invalid values fall back to the 512 KB default with a one-time warning. When an override is active, analyze prints the effective threshold in its startup banner (e.g. CODRAGRAPH_MAX_FILE_SIZE: effective threshold 2048KB (default 512KB)).

Privacy

• All processing happens locally on your machine
• No code is sent to any server
• Index stored in .codragraph/ inside your repo (gitignored)
• Global registry at ~/.codragraph/ stores only paths and metadata

Web UI

CodraGraph also has a browser-based UI at codragraph.vercel.app — 100% client-side, your code never leaves the browser.

Local Backend Mode: Run codragraph serve and open the web UI locally — it auto-detects the server and shows all your indexed repos, with full AI chat support. No need to re-upload or re-index. The agent's tools (Cypher queries, search, code navigation) route through the backend HTTP API automatically.

License

Apache License 2.0

Permissive open source — use, modify, and distribute freely, including commercially.