Cartographer

See your code. Understand your architecture. Navigate with confidence.

Point any codebase at Cartographer. Get an interactive, explorable 3D city where modules are neighborhoods, files are buildings, and dependencies are roads.

Quick Start

npx @bugsbunnycodes1998/cartographer analyze https://github.com/expressjs/express --quick

This clones the repo, analyzes it, and opens a 3D city map in your browser at http://localhost:3742.

Features

• 3D City Visualization — modules as neighborhoods, files as buildings with glowing windows, dependencies as roads with flowing particles
• Health Scoring — composite 0-100 health per file (complexity, churn, test coverage, type safety). Buildings glow green (healthy) to red (critical)
• AI Summaries — OpenAI-powered hierarchical summaries at file, module, and system level
• Git Archaeology — churn analysis, bus factor, contributor mapping, evolution timeline
• Guided Expeditions — auto-generated tours: Grand Tour, Danger Zones, Request Lifecycle
• Building Interiors — zoom into a file to see functions as floors with call connections
• Live Mode — watch for file changes and update the city in real-time via WebSocket
• Multi-Language — TypeScript, JavaScript, Python, Rust, Go, Java
• Cmd+K Search — fuzzy search to fly to any file or module instantly

Installation

npm install -g @bugsbunnycodes1998/cartographer

Requires Node.js 20+.

Usage

Analyze a GitHub repo

# Quick mode (structure only, instant)
cartographer analyze https://github.com/org/repo --quick

# With git history + health scoring
cartographer analyze https://github.com/org/repo --skip-llm

# Full analysis with AI summaries (requires OPENAI_API_KEY)
cartographer analyze https://github.com/org/repo

Analyze a local project

cartographer analyze ./my-project
cartographer analyze . --quick

Live mode (real-time updates)

cartographer live ./my-project

Edit files and watch the city update in your browser.

Options

| Flag | Description | |------|-------------| | --quick | Structure only, no AI/git. Instant results | | --skip-git | Skip git archaeology (churn, bus factor) | | --skip-llm | Skip AI summaries (no OpenAI key needed) | | --root <dir> | Scope analysis to a subdirectory | | --output <dir> | Custom output directory | | --languages <list> | Filter languages (e.g., ts,py) | | --no-serve | Don't open the browser | | -p, --port <n> | Custom port (default: 3742) |

Environment Variables

| Variable | Description | |----------|-------------| | OPENAI_API_KEY | Required for AI summaries and custom expeditions | | CARTOGRAPHER_PORT | Web UI port (default: 3742) |

Navigating the City

| Action | How | |--------|-----| | Pan | Left-click drag | | Rotate | Right-click drag | | Zoom | Scroll wheel | | Select module | Click a neighborhood | | Select file | Click a building | | Enter building | Click "Enter Building" in HUD | | Exit building | Click "Exit Building" or Escape | | Search | Cmd+K / Ctrl+K | | Back to overview | Press Escape | | Expeditions | Click "Expeditions" button |

Visual Encoding

| Visual | Meaning | |--------|---------| | Building height | Lines of code | | Building color (green) | Health 90-100 | | Building color (blue) | Health 70-89 | | Building color (amber) | Health 50-69 | | Building color (orange) | Health 30-49 | | Building color (red) | Health 0-29 | | Road thickness | Coupling strength | | Flowing particles | Data flow direction | | Flame particles | High churn + low health | | Gold shimmer | Excellent health (90+) | | Warning icon | Bus factor = 1 |

Supported Languages

| Language | Parsing | Imports | Modules | |----------|---------|---------|---------| | TypeScript | Full | Full | Barrel files, tsconfig paths | | JavaScript | Full | Full | Barrel files | | Python | Full | Full | __init__.py packages | | Rust | Full | Full | Cargo.toml, mod.rs | | Go | Full | Full | Directory packages, go.mod | | Java | Full | Full | Maven/Gradle, package dirs |

Development

git clone https://github.com/BugBunnyWanders/Cartographer.git
cd Cartographer
pnpm install
pnpm build
node packages/cli/dist/index.js analyze . --quick

License

MIT