Code Mapper

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, 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. Code Mapper 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 code-mapper 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 code-mapper setup once — or set it up manually below.

code-mapper 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 | | 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-code-mapper | pi-code-mapper |

MCP Setup (manual)

If you prefer to configure manually instead of using code-mapper setup:

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

claude mcp add code-mapper -- npx -y code-mapper@latest mcp

Cursor / Windsurf

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

{
  "mcpServers": {
    "code-mapper": {
      "command": "npx",
      "args": ["-y", "code-mapper@latest", "mcp"]
    }
  }
}

OpenCode

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

{
  "mcp": {
    "code-mapper": {
      "command": "npx",
      "args": ["-y", "code-mapper@latest", "mcp"]
    }
  }
}

How It Works

Code Mapper 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
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 .code-mapper/ 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 | |----------|---------| | code-mapper://repos | List all indexed repositories (read first) | | code-mapper://repo/{name}/context | Codebase stats, staleness check, and available tools | | code-mapper://repo/{name}/clusters | All functional clusters with cohesion scores | | code-mapper://repo/{name}/cluster/{name} | Cluster members and details | | code-mapper://repo/{name}/processes | All execution flows | | code-mapper://repo/{name}/process/{name} | Full process trace with steps | | code-mapper://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

code-mapper setup                    # Configure MCP for your editors (one-time)
code-mapper analyze [path]           # Index a repository (or update stale index)
code-mapper analyze --force          # Force full re-index
code-mapper analyze --embeddings     # Enable embedding generation (slower, better search)
code-mapper analyze --verbose        # Log skipped files when parsers are unavailable
code-mapper mcp                     # Start MCP server (stdio) — serves all indexed repos
code-mapper serve                   # Start local HTTP server (multi-repo) for web UI
code-mapper list                    # List all indexed repositories
code-mapper status                  # Show index status for current repo
code-mapper clean                   # Delete index for current repo
code-mapper clean --all --force     # Delete all indexes
code-mapper wiki [path]             # Generate LLM-powered docs from knowledge graph
code-mapper wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)

Multi-Repo Support

Code Mapper supports indexing multiple repositories. Each code-mapper analyze registers the repo in a global registry (~/.code-mapper/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

Code Mapper 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 code-mapper analyze (per-repo) and code-mapper setup (global).

Requirements

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

Privacy

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

Web UI

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

Local Backend Mode: Run code-mapper 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

PolyForm Noncommercial 1.0.0

Free for non-commercial use. Contact for commercial licensing.