⚠️ DEPRECATED — CodeGraph Mapper

CodeGraph Mapper has been merged into coder-workflow (v0.3.0+).

All functionality described below is now available as part of the coder-workflow plugin. See DEPRECATED.md for migration instructions.

---

CodeGraph Mapper (Archived)

Graph-first codebase intelligence for Claude Code.

CodeGraph Mapper scans a repository, builds a SQLite-backed graph of files, symbols, imports, calls, routes, handlers, components, and dependencies, then exposes that graph through Claude skills, MCP tools, CLI commands, exports, and a local UI.

It is built for questions that normal text search cannot answer well:

• Where is this implemented?
• Who calls this function?
• What depends on this module?
• What breaks if this file changes?
• Which routes map to which handlers?
• Which modules are hotspots before refactor?

It also ships a production-grade text search tool for exact literal/regex lookup, so grep/rg becomes fallback instead of default.

Highlights

• Multi-language scanner: JavaScript, TypeScript, Python, Go, Rust, Java.
• SQLite graph store at .codegraph/graph.db.
• Nodes for files, modules, functions, classes, methods, components, routes, handlers.
• Edges for imports, exports, calls, extends, implements, dependencies, route handlers, component usage.
• Graph-backed query, impact analysis, architecture summary, cycles, orphans, quality gates.
• Production text search with literal/regex modes, include/exclude globs, context lines, max-result limits, binary/large-file guards, and structured stats.
• MCP tools for Claude Code workflows.
• Skills and agents for graph-first routing before broad search.
• Local interactive UI with search, filters, zoom, pan, and node detail panels.
• Exports to JSON, Mermaid, DOT/Graphviz, Markdown, and standalone HTML.
• Stop hook support for incremental graph updates.

Quickstart

npm install
npm run build
node dist/cli.js scan
node dist/cli.js summary

If installed globally:

codegraph-mapper scan
codegraph-mapper summary

Then ask Claude Code:

where is scanCodebase implemented?
what depends on src/graph/db.ts?
what calls analyzeGraphQuality?
analyze impact if I change src/analysis.ts
find routes and handlers
search exact text "TODO_AUTH"
regex search "function\\s+scan"
export graph as mermaid and markdown

CLI commands

codegraph-mapper scan
codegraph-mapper update
codegraph-mapper query "scanCodebase"
codegraph-mapper impact "src/graph.ts"
codegraph-mapper cycles
codegraph-mapper orphans
codegraph-mapper summary
codegraph-mapper quality --fail-on medium
codegraph-mapper search "scanCodebase" --case-sensitive
codegraph-mapper search "function\\s+scan" --regex --context 1 --max-results 10
codegraph-mapper export mermaid markdown
codegraph-mapper ui
codegraph-mapper mcp

Command guide:

Command	Purpose
scan / update	Build or refresh .codegraph/graph.db.
query	Find files, symbols, imports, exports, dependencies, routes, handlers, callers/callees.
impact	Show upstream/downstream blast radius for a file, symbol, or module.
cycles	Detect circular relationships.
orphans	Find disconnected files or symbols.
summary	Summarize architecture, directories, metadata, and hotspots.
quality	Report unresolved imports, duplicates, stale graph data, coverage, and quality gate result.
search	Exact literal/regex text search with safe limits and structured stats.
export	Write graph artifacts: JSON, Mermaid, DOT, Markdown, HTML.
ui	Launch local graph explorer.
mcp	Start MCP server for Claude Code.

Graph search vs text search

Use graph search when the question is about structure:

codegraph-mapper query "scanCodebase"
codegraph-mapper impact "src/analysis.ts"
codegraph-mapper summary

Use text search when the question is about exact content:

codegraph-mapper search "TODO"
codegraph-mapper search "scanCodebase" --case-sensitive
codegraph-mapper search "function\\s+scan" --regex --context 2
codegraph-mapper search "openGraphDb" --include "src/**/*.ts" --exclude "**/*.test.ts"

Text search returns:

{
  "results": [
    {
      "file": "src/graph.ts",
      "line": 47,
      "column": 17,
      "text": "export function scanCodebase(root: string, settings: CodeGraphSettings): CodeGraph {",
      "contextBefore": [],
      "contextAfter": ["  const files = listSourceFiles(root, settings);"],
      "fileSizeBytes": 9295,
      "matchLength": 12
    }
  ],
  "stats": {
    "filesConsidered": 25,
    "filesSearched": 25,
    "filesSkipped": 0,
    "binaryFilesSkipped": 0,
    "oversizedFilesSkipped": 0,
    "readErrors": [],
    "totalMatches": 1,
    "truncated": false
  }
}

Why use built-in search instead of raw grep:

• respects CodeGraph language and ignore settings
• supports literal and regex search
• supports --include / --exclude globs
• skips binary files
• skips oversized files
• protects result volume with --max-results
• reports truncation and read errors
• returns machine-readable JSON for Claude/MCP workflows

MCP tools

The bundled MCP server exposes graph and search tools to Claude Code:

Tool	Purpose
scan_codebase	Build/refresh graph.
query_graph	Query definitions, references, callers, dependencies, routes, components.
search_code	Safe literal/regex text search across source files.
analyze_impact	Analyze upstream/downstream change impact.
summarize_architecture	Summarize architecture and hotspots.
find_cycles	Detect circular dependencies.
find_orphans	Detect orphan files/symbols.
analyze_quality	Produce graph quality report.
quality_gate	Evaluate quality gate threshold.
export_graph	Export graph artifacts.
open_graph_ui	Start interactive local graph UI.

Recommended workflow

1. Scan once after meaningful changes.
2. Ask graph questions first for architecture, dependencies, flow, callers, and impact.
3. Use built-in search / search_code for exact literal or regex text lookup.
4. Use impact before refactors.
5. Use quality --fail-on medium before merge.
6. Use export or ui when sharing architecture context.

This gives Claude better signal than broad grep because it starts from code relationships, then falls back to safe text search only when needed.

Plugin surface

• skills/: scan, query, analyze, export, open UI, and orchestration workflows.
• agents/: graph builder and graph analyst subagents.
• commands/: plugin slash commands.
• hooks/: Claude Code hook definitions, including Stop update workflow.
• .claude-plugin/plugin.json: plugin manifest.
• .mcp.json: MCP server configuration.

Runtime data

Runtime graph data lives under .codegraph/ in each analyzed project:

.codegraph/
  graph.db
  exports/
  ui/

Notes:

• .codegraph/graph.db stores nodes, edges, metadata, indexes, and scan cache.
• .codegraph/exports/ contains generated JSON/Mermaid/DOT/Markdown/HTML artifacts when exported.
• .codegraph/ui/ contains local UI runtime assets.
• Generated runtime data should usually stay uncommitted unless your team explicitly wants graph artifacts in git.

CodeGraph Mapper respects target-project .gitignore by default. ignorePaths adds CodeGraph-specific exclusions that should not live in .gitignore.

Local development

From this repository:

npm install
npm run build
npm run typecheck
npm run test

Useful checks:

npm run check
node --test dist/test/graph.test.js
node --test dist/test/search.test.js
node dist/cli.js scan
node dist/cli.js quality --fail-on medium

Run Claude with local plugin directory:

claude --plugin-dir /mnt/code/djnaidwhbwda/codegraph-mapper

Then ask Claude to scan, query, search, export, or analyze the graph.

Global install

Install the package globally, then point Claude at the installed plugin directory:

npm install -g /mnt/code/djnaidwhbwda/codegraph-mapper
claude --plugin-dir "$(npm root -g)/codegraph-mapper"

After that, codegraph-mapper is available as a global CLI.

Installing as a Claude plugin

Quick install (recommended)

Install skills, hooks, agents, and MCP server to Claude Code:

./install.sh

This will:

1. Build the project
2. Install codegraph-mapper globally
3. Configure MCP server in ~/.claude.json (user scope, available in all projects)
4. Copy skills, agents, and hooks to ~/.claude/

Then restart Claude Code and the MCP tools will be available in all your projects.

Install options

# Install everything to user scope (default, available in all projects)
./install.sh

# Install MCP server only (skip skills/agents/hooks)
./install.sh --mcp-only

# Install to project scope (.mcp.json in project root, committed to repo)
./install.sh --project

# Link instead of copy (for development)
./install.sh --link

# Install specific skills only
./install.sh query-codegraph analyze-codegraph

# Skip commands installation
./install.sh --no-commands

Manual setup

If you prefer manual setup:

Local development

npm install
npm run build
claude --plugin-dir /path/to/codegraph-mapper

Then add MCP server to ~/.claude.json:

claude mcp add --transport stdio codegraph -- /path/to/codegraph-mapper/dist/cli.js mcp

Global install

npm install -g /path/to/codegraph-mapper
claude --plugin-dir "$(npm root -g)/codegraph-mapper"

Then add MCP server:

claude mcp add --transport stdio codegraph -- codegraph-mapper mcp

Developer link

cd /path/to/codegraph-mapper
npm link
npm link codegraph-mapper
claude --plugin-dir "$(npm root -g)/codegraph-mapper"

Then add MCP server:

claude mcp add --transport stdio codegraph -- codegraph-mapper mcp

Verify MCP is working

codegraph-mapper mcp

Stop with Ctrl+C. If the server starts without errors, MCP is ready.

Check in Claude Code:

/mcp

You should see codegraph listed with available tools.

Configuration

Create .claude/codegraph-mapper.local.md in target projects:

---
languages:
  - javascript
  - typescript
  - python
  - go
  - rust
  - java
ignorePaths:
  - node_modules
  - .git
  - dist
  - build
  - .next
  - vendor
  - .codegraph/cache
updateOnStop: true
updateOnEdit: false
commitGraphJson: false
maxDepth: 4
uiPort: 3737
exports:
  - json
  - mermaid
  - dot
  - markdown
---

Project-specific CodeGraph Mapper settings.

Production readiness checklist

Before relying on graph output in CI or review workflows:

codegraph-mapper scan
codegraph-mapper quality --fail-on medium
codegraph-mapper cycles
codegraph-mapper orphans

Healthy signal:

• quality gate passes
• no unexpected cycles
• no unexpected orphans
• relationship coverage is high
• hotspots are understood before refactor

License

MIT or project-defined license.