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:

Structure — Walks the file tree and maps folder/file relationships
Parsing — Extracts functions, classes, methods, and interfaces using Tree-sitter ASTs
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
Clustering — Groups related symbols into functional communities
Processes — Traces execution flows from entry points through call chains
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.

Keywords

mcp

model-context-protocol

FAQs

What is @codragraph/cli?

Is @codragraph/cli popular?

Is @codragraph/cli well maintained?

Package last updated on 30 Apr 2026

@codragraph/cli

CodraGraph

Why?