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, or which files make up a product area like Settings, Auth, AI, or Billing. CodraGraph fixes this by precomputing every dependency, call chain, feature cluster, 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.

The same CLI commands work in Windows PowerShell, macOS bash/zsh, and Linux shells. Use npx @codragraph/cli ... for no-install runs or codragraph ... after a global install.

Smart analyze rebuilds when indexed source, Markdown/MDX graph docs, language config, schema, compression, or requested embedding settings changed. Generated agent context, lockfile-only, and ignored asset changes reuse the existing graph and advance metadata. Each pass refreshes .codragraph/structure/, a compact what/why/how/when/where markdown pack with branch/index state, bounded history, and SQLite seed SQL for external agent memory.

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

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

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@2.1.5 mcp

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

Codex (full support — MCP + skills)

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

Cursor / Windsurf

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

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

OpenCode

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

{
  "mcp": {
    "codragraph": {
      "command": "npx",
      "args": ["-y", "@codragraph/cli@2.1.5", "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 structural communities
5. Processes — Traces execution flows from entry points through call chains
6. Feature clusters — Builds human-facing product/domain areas with members, dependencies, and line ranges
7. 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:

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

MCP Resources

MCP Prompts

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 feature-clusters         # List product/domain feature areas
codragraph cluster-query settings   # Search product/domain feature areas
codragraph feature-context Settings # Focus files, line ranges, flows, dependencies for one feature
codragraph context-pack Settings    # Compact agent context pack for one feature
codragraph cluster-impact Settings --direction both  # Feature-level blast radius
codragraph mcp                     # Start MCP server (stdio) — serves all indexed repos
codragraph serve                   # Start local HTTP API + bundled web UI
codragraph serve --web hosted      # API only; connect from hosted 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:

# macOS/Linux bash/zsh
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

# Windows PowerShell
$env:CODRAGRAPH_EMBEDDING_URL = "http://your-server:8080/v1"
$env:CODRAGRAPH_EMBEDDING_MODEL = "BAAI/bge-large-en-v1.5"
$env:CODRAGRAPH_EMBEDDING_DIMS = "1024"
$env:CODRAGRAPH_EMBEDDING_API_KEY = "your-key"
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.

For one product spread across many repos, use codragraph group ... plus repo: "@<group>" in MCP tools. feature_clusters, feature_context, and cluster_impact fan out across members and include contract-aware cross-repo cluster links when the group Contract Registry has matching provider/consumer edges.

Supported Languages

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

Language Feature Matrix

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 >= 20
• 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 current workspace version, or pin the version your team has validated:

npx @codragraph/cli@2.1.5 analyze          # no global install
# or
npm install -g @codragraph/cli@2.1.5       # upgrade a global install

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

npm install -g npm@10                # update npm within the Node 20 line
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 on macOS/Linux bash/zsh
NODE_OPTIONS="--max-old-space-size=16384" npx @codragraph/cli analyze

# Windows PowerShell
$env:NODE_OPTIONS = "--max-old-space-size=16384"
npx @codragraph/cli analyze

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

If the analyzer reports a worker sub-batch timeout or falls back to sequential parsing while files are still being processed, reduce worker batch memory and allow a longer idle window:

# macOS/Linux bash/zsh
CODRAGRAPH_WORKER_SUB_BATCH_SIZE=100 CODRAGRAPH_WORKER_IDLE_TIMEOUT_MS=180000 npx @codragraph/cli analyze

# Windows PowerShell
$env:CODRAGRAPH_WORKER_SUB_BATCH_SIZE = "100"
$env:CODRAGRAPH_WORKER_IDLE_TIMEOUT_MS = "180000"
npx @codragraph/cli analyze

The worker timer is an idle guard. Parser progress resets it, so a slow repo should keep moving instead of paying the old 30-second wall-clock fallback.

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 on macOS/Linux bash/zsh
export CODRAGRAPH_MAX_FILE_SIZE=2048
npx @codragraph/cli analyze

# Windows PowerShell
$env: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 http://localhost:4747. The installed CLI serves the bundled dashboard from dist/web and does not package apps/web/node_modules. It auto-detects the server and shows all your indexed repos, feature clusters, dependency context, and 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.

Hosted Dashboard Mode: Run codragraph serve --web hosted, then open the hosted dashboard and connect it to http://localhost:4747. The UI is hosted, but project data still comes from your local API.

License

Apache License 2.0.

Permissive open source. You can use, modify, redistribute, bundle, and host the CLI commercially, subject to the Apache-2.0 notice and attribution requirements.