CodeCartographer

A codebase diagram builder combining the best of CodeGraphContext and GitNexus.

What It Does

CodeCartographer parses TypeScript/TSX codebases, builds a queryable graph, and generates:

• Architecture diagrams — clusters, execution flows, complexity hotspots, dead code
• AI agent skills — auto-generated .claude/skills/ per functional domain
• Impact analysis — blast radius before you refactor
• 360° symbol context — callers, callees, imports in one view

Why It Exists

Tool	Strength	Weakness
CGC	Precise call graphs, Cypher queries	Broken on @/ aliases, no auto-skills
GitNexus	Auto-skills, clusters, semantic search	File-level callers only, slow indexing
CodeCartographer	Function-level precision + alias resolution + auto-skills	In-memory only (no graph DB backend yet)

Install

npm install -g codecartographer
# or
npx codecartographer <command>

Quick Start

# Index a codebase
codecartographer index ~/my-project

# Generate a full diagram
codecartographer diagram ~/my-project

# Generate AI agent skills
codecartographer skills ~/my-project

# Look up a symbol
codecartographer context calculateBuffettScore ~/my-project

# Impact analysis
codecartographer impact calculateBuffettScore ~/my-project

# Search
codecartographer query "portfolio holdings" ~/my-project

MCP Server

Connect to Claude Code, Cursor, or any MCP-compatible IDE:

# Add to your MCP config
{
  "mcpServers": {
    "codecartographer": {
      "command": "npx",
      "args": ["-y", "codecartographer", "mcp"]
    }
  }
}

Exposed tools:

• codecartographer_index — index a codebase
• codecartographer_diagram — generate structured diagram
• codecartographer_context — 360° symbol view
• codecartographer_impact — blast radius analysis
• codecartographer_query — search the graph
• codecartographer_skills — generate skill files

Architecture

Parser (TypeScript Compiler API)
  ↓
Graph (in-memory JSON, pluggable backend)
  ↓
Analyzer (clusters, flows, complexity, dead code)
  ↓
Skills Generator → .claude/skills/generated/
  ↓
CLI / MCP Server

How It Differs

Path Alias Resolution

CGC returns 0 results for @/lib/... imports. CodeCartographer reads tsconfig.json and resolves aliases correctly.

Function-Level Call Graphs

GitNexus shows file-level callers only. CodeCartographer tracks exact function-to-function calls with confidence scoring.

Build Artifact Exclusion

Neither tool excludes .next/, dist/, or node_modules/ well. CodeCartographer hardcodes exclusions and respects .gitignore.

Naming Collision Detection

CGC missed that calculateBuffettScore exists in two files. CodeCartographer detects and disambiguates.

Roadmap

• KùzuDB / Neo4j backend option
• Semantic search (BM25 + embeddings)
• Web UI (Sigma.js visualization)
• Incremental indexing
• Git-aware change detection
• React component hierarchy
• Engram persistent memory integration

License

MIT