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

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)

---

## 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

```bash
# 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 now patches the existing graph for normal day-to-day changes:
source edits, renames, large diffs, and topology-only files replace only the
affected file-scoped rows, then recompute communities, execution flows, and
FeatureCluster packs. Package/config or ignore-rule inputs refresh all
file-scoped rows without falling back to a full cold rebuild. 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

| 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](https://pi.dev) | `pi install npm:pi-codragraph` | [pi-codragraph](https://github.com/tintinweb/pi-codragraph) |

## MCP Setup (manual)

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

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

```bash
# macOS / Linux
claude mcp add codragraph -- npx -y @codragraph/cli@2.2.0 mcp

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

### Codex (full support — MCP + skills)

```bash
codex mcp add codragraph -- npx -y @codragraph/cli@2.2.0 mcp
```

### Cursor / Windsurf

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

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

### OpenCode

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

```json
{
  "mcp": {
    "codragraph": {
      "command": "npx",
      "args": ["-y", "@codragraph/cli@2.2.0", "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:

| 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 |
| `feature_clusters` / `cluster_query` | Product/domain feature map for targeted context | Optional |
| `feature_context` / `cluster_context` / `context_pack` | Files, line ranges, dependencies, and flows for one feature | Optional |
| `cluster_impact` | Feature-level blast radius and safe edit surface | 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}/feature-clusters` | Product/domain feature areas |
| `codragraph://repo/{name}/feature/{name}` | Focused feature context pack |
| `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 simple Mermaid diagrams |

## CLI Commands

```bash
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 detect-changes --scope unstaged  # Map working-tree diff to symbols/processes
codragraph detect-changes --scope all       # Include staged + unstaged changes
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:

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

| 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 >= 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.)

```bash
# 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](https://github.com/npm/cli/issues/8126)).
It is fixed in **codragraph v1.6.2+**. Upgrade to the current workspace
version, or pin the version your team has validated:

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

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

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

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

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

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

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

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

```bash
# 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](https://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](https://www.apache.org/licenses/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.