Know where you are in the code.
A local-first navigation system for software architecture.
Product site · Quick Start · Cursor · CLI · Sponsor
Cartographer ships as a Cursor plugin (slash commands, skill, agent, rules, MCP) plus a local CLI built from this repository.
Marketplace listing is pending Cursor approval. Until it appears in the Cursor Marketplace, install from this repository: local plugin + CLI from source (or GitHub Releases). Local install works today.
This project is not an npm registry package. There is no npm install -g cartographer. package.json exists for local Node scripts, dependencies, and bins — clone → build → use.
Open a foreign repository. Run one command. See the map in about fifteen seconds.
The Living Atlas Briefing is Cartographer’s flagship moment: a single high-signal orientation that answers where am I, what kind of system is this, how do the pieces usually flow, and where should I start. It is not a chat summary. It is a structured map assembled from the same Atlas that powers every other command.
$ cartographer whereami src/api/handlers.ts 12
┌────────────────────────────────────────────────────────┐
│ CARTOGRAPHER · LIVING ATLAS BRIEFING │
│ checkout-service │
└────────────────────────────────────────────────────────┘
Survey 142 files · 1,840 symbols · 3,102 edges
Map 8 territories · 12 entries · coverage 12%
▸ YOU ARE HERE
API › handlers › checkout.ts › function:createOrder
Territory: API (82% confidence)
▸ MINI ATLAS
├─ API ████████░░░░ 420 82%
├─ Domain ██████░░░░░░ 310 77%
├─ Data █████░░░░░░░ 280 74%
└─ Workers ███░░░░░░░░░ 120 68%
▸ TOP CORRIDORS
→ API → Domain → Data ×18
Requests typically flow API → Domain → Data.
▸ HUBS & BRIDGES
[BRIDGE] OrderService
OrderService is a bridge between API ↔ Domain ↔ Data.
▸ START HERE
Journey: Start at the edge
First: POST /orders
Why: Begin at http entry, then walk downstream.
cartographer brief, whereami, tour, and a fresh index all share this briefing — the same hubs, corridors, territories, and fog-of-war that power navigation.
cartographer brief
cartographer brief src/api/handlers.ts 12
cartographer whereami src/api/handlers.ts 12Modern codebases are large graphs pretending to be folders. You open a file and lose the architecture: which territory you are in, what usually flows where, which symbols are hubs, and what remains unexplored.
Cartographer builds a persistent Atlas for a repository — a local SQLite map of symbols, relationships, territories, corridors, hubs, landmarks, journeys, and exploration state — then exposes that map through CLI, MCP, and Cursor surfaces.
| Without Cartographer | With Cartographer |
|---|---|
| “Where should I start?” | Living Atlas Briefing + start-here journey |
| “What is this file for?” | whereami breadcrumb + territory confidence |
| “How does A reach B?” | Corridor-aware route / explain-route |
| “What depends on this?” | upstream / downstream neighborhoods |
| “What have we not charted?” | Fog-of-war via unexplored |
Design principles
- Orientation before change — know where you are before you edit.
- One Atlas facade — CLI, MCP, and Cursor commands share the same core.
- Local-first — no telemetry, no required cloud, no API keys for core navigation.
- Cartographic language — territories, corridors, hubs, bridges, landmarks, journeys, fog.
Requires Node.js 20+ (22/24 recommended). Uses built-in node:sqlite. No API keys.
git clone https://github.com/theworker02/cartographer.git
cd cartographer
npm install
npm run build
npm link # optional — adds `cartographer` to your PATH for local useThen, in any project you want to map:
cd /path/to/your/project
cartographer index
cartographer briefindex surveys the repository, writes .cartographer/atlas.db, and prints a Living Atlas Briefing by default. After that, navigate with whereami, route, hubs, unexplored, and the rest of the CLI.
Docs site (live): theworker02.github.io/cartographer
Install guide: Install
Cartographer is a Cursor plugin. Manifest: .cursor-plugin/plugin.json.
Marketplace listing is pending Cursor approval. Until then, install from this repository as a local plugin. Build dist/ first so MCP and CLI entrypoints resolve (npm install && npm run build at the repo root).
What the plugin includes:
| Surface | Location | Role |
|---|---|---|
| Slash commands | commands/ |
brief, whereami, route, goto, tour, unexplored, index, doctor, … |
| Skill | skills/cartographer |
Teaches the agent Atlas-first orientation |
| Agent | agents/cartographer-navigator |
Navigator persona for unfamiliar repos |
| Rules | rules/cartographer.mdc |
Persistent cartographic guidance |
| Hooks | hooks/hooks.json |
Plugin hooks |
| MCP | mcp.json → dist/mcp/index.js |
Same Atlas tools for agent tooling |
Point Cursor at this checkout as a local plugin, open a project, run cartographer index (CLI or MCP), then ask for a briefing or use /whereami-style commands.
The Atlas is Cartographer’s source of truth: a durable map under .cartographer/ in the target repository.
atlas.db— SQLite store of files, symbols, relationships, territories, and derived map layersconfig.toml— optional per-repo configuration (created on demand)- Landmarks / journeys / exploration — JSON alongside the database for annotations and fog-of-war
Indexing is deterministic and incremental-friendly. Re-running cartographer index refreshes the map; landmark drift is checked so named places stay honest as code moves.
Everything else — briefing, routes, hubs, MCP tools — reads this Atlas through a single Atlas facade. Surfaces do not invent a second graph.
Territories are inferred architectural regions (API, Domain, Data, Workers, Config, and similar), scored with confidence and internal density.
cartographer territoriesThey appear in the Mini Atlas tree inside every Living Atlas Briefing, and they constrain how routes and corridors are explained: moving API → Domain → Data is a corridor, not a random hop list.
whereami (alias where) answers the human question first: where am I in the architecture?
cartographer whereami path/to/file.ts 42
cartographer whereami path/to/file.ts 42 --compact # breadcrumb only
cartographer brief # repo-level briefing
cartographer brief path/to/file.ts 42 # briefing pinned to a locationFull mode returns the Living Atlas Briefing with a YOU ARE HERE breadcrumb (territory + confidence). Compact mode prints the breadcrumb alone when you already know the map.
Routes find paths between symbols (or file:line coordinates) with corridor awareness — preferring paths that follow how the system usually flows.
cartographer route OrderController OrderRepository
cartographer explain-route OrderController OrderRepositoryEach route reports score, hops, territory transitions, and a plain-language explanation. Prefer explain-route when you want the best path narrated without the full candidate set.
Neighborhood queries over the relationship graph:
cartographer upstream createOrder -d 3
cartographer downstream OrderService -d 3- Upstream — who reaches this symbol?
- Downstream — what does this symbol reach?
Useful for blast-radius checks, onboarding (“what does this service touch?”), and validating that a change stays inside the expected territory.
Landmarks are human-named places on the map — “checkout entry”, “payment gateway”, “legacy invoice path” — pinned to a file:line with a description.
cartographer landmarks
cartographer landmarks --add "Checkout entry" --file src/api/orders.ts --line 12 \
--description "HTTP entry for create order"On re-index, Cartographer checks landmark drift so annotations do not silently point at the wrong code. Drifted landmarks show up in status and doctor.
Journeys are ordered stops for guided walks through the architecture — onboarding paths, “start at the edge”, or custom tours of a subsystem.
cartographer journeysGenerated journeys (for example from entry points) are marked so you can tell Atlas-suggested walks from hand-authored ones. The Living Atlas Briefing’s START HERE suggestion is typically the first stop of a journey worth taking.
tour combines a Living Atlas Briefing with a walkable journey:
cartographer tour
cartographer tour "Start at the edge"You get orientation first, then numbered stops with purpose — ideal for pairing, agent handoffs, or your first hour in an unfamiliar service.
Cartographer tracks what you have charted versus what remains in the fog:
cartographer unexplored
cartographer statusFog layers:
- Understood — territories / areas you have engaged
- Frontier — adjacent, high-value next places to chart
- Beyond — still unmapped relative to current exploration
Coverage appears in the briefing and in status. Exploration can be disabled in config if you want a pure static map without fog tracking.
When Git history is available locally, Cartographer can surface recent archaeology for a file, symbol, or territory:
cartographer history
cartographer history src/api/orders.ts
cartographer history OrderServiceBranch and revision are recorded at index time and shown in status. History is read from the local repo only — nothing is uploaded. Toggle with [git] history in .cartographer/config.toml.
v0.2 ships deterministic language adapters (no native tree-sitter binary required):
| Language | Notes |
|---|---|
| TypeScript / JavaScript | Incl. TSX; route and entry heuristics |
| Python | Flask / FastAPI, Click |
| Go | Handlers, Cobra |
| Rust | Axum / Actix, Clap / Tauri |
Adapters extract symbols, imports, calls, and entry points. Cross-file linking, territory inference, hubs, and corridors run in core. See Languages.
Global option: -C, --cwd <path> to target a repository root.
| Command | Purpose |
|---|---|
index |
Survey the repo and build / refresh the Atlas (+ briefing by default) |
brief |
Living Atlas Briefing (flagship) |
whereami / where |
Breadcrumb + briefing for file:line |
goto |
Resolve symbol / file:line to Atlas coordinates |
route / explain-route |
Corridor-aware paths between symbols |
upstream / downstream |
Graph neighborhoods |
territories / hubs / corridors |
Map layers |
landmarks / journeys / tour |
Annotations & guided walks |
unexplored |
Fog-of-war frontiers |
search |
Concept search across territories, landmarks, entries, hubs, symbols |
history |
Git-aware history for file / symbol / territory |
status / doctor |
Health, coverage, landmark drift, integrity |
Most commands accept --json for machine-readable output (agents, scripts, CI).
cartographer index --incremental
cartographer index --no-brief
cartographer status --brief
cartographer doctorThe MCP server exposes the same Atlas facade to agents:
cartographer_brief
cartographer_whereami
cartographer_goto
cartographer_route
cartographer_upstream
cartographer_downstream
cartographer_territories
cartographer_hubs
cartographer_search
cartographer_unexplored
cartographer_tour
cartographer_doctor
cartographer_status
cartographer_index
Configured via mcp.json (plugin) to run node ${PLUGIN_ROOT}/dist/mcp/index.js with CARTOGRAPHER_ROOT set to the workspace folder. Build dist/ before expecting MCP tools to resolve.
Standalone:
npm run mcp
# or
cartographer-mcpOptional file: .cartographer/config.toml in the target repository.
# Cartographer repository configuration
version = 1
[index]
exclude = [
"node_modules",
"target",
"dist",
"vendor",
"build",
".git",
"coverage",
"__pycache__",
".venv",
"venv"
]
include_vendored = false
max_file_bytes = 1500000
[exploration]
enabled = true
[git]
history = trueAdditional ignore patterns: .cartographerignore (gitignore-style lines). Defaults skip common build and dependency trees; raise max_file_bytes only if you intentionally index very large generated sources.
One consolidated TypeScript project — not a constellation of micro-packages, and not an npm library product.
core/ Atlas facade, indexer, territories, routes, briefing, doctor
adapters/ Language extractors (TS/JS, Python, Go, Rust)
cli/ cartographer binary
mcp/ MCP server
commands/ Cursor slash commands
skills/ Cursor skill
agents/ Cursor agent
rules/ Cursor rules
docs-site/ GitHub Pages product + docs
assets/ Banner, logos, mark
Pipeline
- Adapters extract symbols and relationships per language.
- Indexer builds / refreshes the SQLite Atlas in
.cartographer/. - Core infers territories, corridors, hubs/bridges, entry points; tracks exploration; checks landmark drift.
- Atlas facade powers CLI, MCP, and Cursor — one API, one map.
More detail: Architecture.
Cartographer is designed for interactive orientation, not overnight whole-company crawls.
- Incremental indexing (
cartographer index --incremental) limits work to changed files when possible. - Large / vendored trees are excluded by default;
.cartographerignorekeeps noise out of the Atlas. - File size caps avoid swallowing huge generated blobs into the graph.
- Briefing, hubs, and corridors are derived from the indexed graph — cheap relative to a full re-survey.
For rough timing on your machine: npm run bench (runs cartographer index --bench after build). Prefer Node 22/24 for node:sqlite ergonomics.
Cartographer is local-first by design.
- No telemetry, analytics, or phone-home
- No required API keys or cloud account for core navigation
- Atlas data lives in
.cartographer/on your machine - Git history is read locally when enabled
- The docs site is static GitHub Pages — it does not process your code
Treat .cartographer/ like any other project cache: it may mirror paths and symbol names from your codebase. Full statement: Privacy.
Supported releases and reporting process: SECURITY.md.
Report vulnerabilities privately via GitHub Security Advisories on theworker02/cartographer. Do not open public issues for problems that could expose repository contents or local Atlas data.
Directions under active consideration (not a schedule):
- Richer multi-language depth and entry-point heuristics
- Deeper incremental / watch-mode indexing for large monorepos
- Stronger corridor explanations and journey authoring UX
- Cursor Marketplace listing once approved
- Optional tree-sitter-backed parsers where deterministic adapters hit limits
- Packaging refinements via GitHub Releases (still not an npm registry product)
Ideas and PRs that strengthen navigation UX over unrelated tooling are especially welcome.
See CONTRIBUTING.md.
npm install
npm run build
npm test
npm run validate:pluginGuidelines in short: keep features behind the Atlas facade; prefer navigation upgrades; match the cartographic aesthetic; add tests for indexer / briefing / graph behavior; use conventional commits (feat, fix, docs, test, chore).
Code of conduct: CODE_OF_CONDUCT.md.
Cartographer is independent open source. If the Atlas saves you time in foreign codebases, consider supporting development:
- GitHub Sponsors: github.com/sponsors/theworker02
- thanks.dev: thanks.dev/u/gh/theworker02
Sponsors and thanks.dev are external platforms with their own privacy policies; Cartographer itself never sees payment data.
- Changelog: CHANGELOG.md
- Releases: github.com/theworker02/cartographer/releases
- Docs: theworker02.github.io/cartographer