Cartographer indexes a repo into SQLite so agents read bounded briefs

The repository becomes a SQLite graph you can query

Cartographer started as a Claude Code plugin that mapped codebases with parallel subagents, and version 2 keeps that legacy path while adding something more mechanical underneath it. The v2 description is a graph CLI for intelligent coding agents: index a repo into a local SQLite graph, compile bounded briefs, run removal and completeness audits, manage evidence-backed notes, and score whether agents used graph context before editing.

The index command is the foundation. It builds .cartographer/manifest.json, .cartographer/graph.sqlite, JSON schemas, and CODEBASE_MAP.md inside the .cartographer directory. The graph is local, in SQLite, next to the project, which means the index is a file you can copy, diff or delete like any other build output.

The caching story matters more than it first appears. Unchanged repos reuse prior artifacts through a SQLite file-hash cache, unless --force or --no-incremental is passed. On a large repository, re-indexing on every agent run would make the tool unusable, and the hash cache is what makes an incremental graph possible.

There is a companion check for that. The verify command checks graph artifact compatibility and, with --fresh, fails when persisted artifacts drift from the live repo. So the tool can answer two different questions: are these artifacts still loadable, and do they still describe the code as it is now. The second is the one that matters if an agent is about to trust the graph.

brief is the command that replaces a whole-repo prompt

The brief command emits bounded agent-facing context around a path, package, symbol, env var, DB or IaC object, audit ledger, or changed files. Bounded is the operative word. The command is described as compiling briefs, and the point of a bound is that the output has a size limit an agent can actually consume, rather than a token count that scales with the repository.

The invocation looks like this:

bun run cartographer:brief -- --out .cartographer --path src/index.ts --mode implementation --json

The mode is a parameter, and implementation is one of the values, which implies that the same path can be compiled for different purposes, such as reading what a file does rather than how it is implemented. The README does not enumerate every mode, so treat the mode list as something to discover from the command's own help output.

Around the brief sit other graph surfaces with the same purpose. slice, impact, context and preflight are described as compatibility and debug graph surfaces, and they come with a guard rail: broad selectors require --allow-broad or --debug-graph. That guard is the interesting design decision. A graph tool can answer a huge question if you let it, and a huge answer is exactly what an agent cannot use. Requiring an explicit flag to widen the selector keeps the default narrow, which is the behaviour that makes the tool usable in an automated loop.

The adoption command closes the loop by scoring graph-first behavior from runtime traces. That is a measurement of whether agents actually used the graph, which is a different question from whether the graph is accurate.

Removal audits and notes give the agent a ledger to keep

Two command families handle state that outlives a single prompt.

The first is the audit ledger. The commands audit removal and audit verify create and verify task-specific removal ledgers, so that when an agent is asked to remove something, for instance a dependency or a service, the removal is recorded as an artefact rather than asserted in chat. A removal audit runs like this:

bun run cartographer:audit -- removal --out .cartographer --target supabase --write .cartographer/audits/supabase-removal.json

The target is named on the command line and the ledger is written to a JSON file under .cartographer/audits. The verify counterpart then checks such a ledger against the graph, which is how a task scoped as a removal gets verified rather than assumed complete.

The second is notes, described as evidence-backed semantic notes, managed through notes ingest, notes audit, notes accept and notes retire. The four verbs describe a lifecycle. Something is ingested, it is audited, it is either accepted or retired. A note that is not accepted does not become part of the trusted context, which is a meaningful difference from a comment file that accumulates.

Read together, these two features point at the same idea. An agent that edits a large repository needs somewhere to record what it found and what it removed, in a form that a later run can check. The legacy annotate and annotations commands are described as a legacy OpenRouter annotation workflow, superseded for daily use by notes, so the project is still migrating its own vocabulary.

The MCP wrapper is a thin bridge, and the README says so

Cartographer can be exposed to an agent over the Model Context Protocol. The mcp command runs a thin newline-delimited MCP stdio wrapper over Cartographer graph operations, and the exposed tools are cartographer_index, cartographer_view, cartographer_brief, cartographer_context, cartographer_preflight, cartographer_verify, cartographer_audit_removal, cartographer_audit_verify, cartographer_notes_audit, and cartographer_diff.

The README is unusually clear about the boundary: it wraps the same library functions as the CLI, and it does not become a long-lived graph brain or agent manager. That sentence matters for anyone wiring this into an agent runtime. There is no daemon holding state between calls, no background indexing service, and no model in the loop. The agent calls a tool, the tool runs a function, the answer comes back.

The consequence is that all the state lives in the .cartographer directory. If an agent session runs in a sandbox that is reset between tasks, the graph has to be rebuilt or mounted, and the incremental cache only helps when the artifacts are still there.

There is also a diff command, for comparing two graph artifact directories, which suggests the intended workflow of keeping one indexed copy per branch and comparing them. The export command explicitly exports full debug JSON or JSONL graph data, which is what you would use to look at the graph with other tools.

Installing and indexing a repository with bun

The v2 CLI is a Bun project. Installing the dependencies is one command:

bun install

After that, the commands are driven through the package scripts. The help output comes first, and then the index step that builds the graph:

bun run cartographer -- --help
bun run cartographer:index -- --root . --out .cartographer

The root and out flags make the target directory and the artifact directory explicit, so the same command works on a subdirectory of a monorepo rather than only on the current working directory. Once the graph exists, you can summarize it, verify it, and compile a brief:

bun run cartographer:verify -- --out .cartographer --root . --fresh
bun run cartographer:view -- --out .cartographer
bun run cartographer:brief -- --out .cartographer --path src/index.ts --mode implementation --json

The verify invocation with --fresh is the one to run in a pipeline, since it is the check that fails when the persisted artifacts no longer match the repository.

The project also ships deterministic eval profiles, which are worth knowing about because they show how the author expects the tool to be checked:

bun run eval:cartographer:smoke
bun run eval:cartographer:codex
bun run eval:cartographer:codex:live

The README describes the smoke, recorded Codex-trace and explicit live Codex profiles as indexing this repo and using an external path as a read-only target, writing graph artifacts under /tmp and append-only JSON reports under docs/reports. A live profile implies network calls and a real model, so treat it as an optional check rather than something to wire into every run.

The legacy plugin path still produces docs/CODEBASE_MAP.md

The installation section documents the older Claude Code plugin workflow, and the README is careful to say it is separate from the v2 graph CLI and that new agent and orchestrator workflows should prefer the v2 brief, audit and notes commands.

Installing it means adding a marketplace and installing the plugin, then restarting Claude Code:

/plugin marketplace add kingbootoshi/cartographer

/plugin install cartographer

After the restart, the skill is invoked with /cartographer, or by asking Claude to map this codebase, which triggers it automatically.

What it produces is a document rather than a graph. Cartographer orchestrates multiple Sonnet subagents to analyse the entire codebase in parallel, then synthesises their findings into docs/CODEBASE_MAP.md, a detailed architecture map with file purposes, dependencies, data flows and navigation guides, and it updates CLAUDE.md with a summary pointing at the map.

The mechanism is four steps: a scanner script produces the file tree with token counts and respects .gitignore, the work is split across subagents based on token budgets, the Sonnet subagents analyse their portion in parallel, and their reports are synthesised into the documentation.

There is an update mode, which is the part that makes it usable over time. If docs/CODEBASE_MAP.md already exists, Cartographer checks git history for changes since the last mapping, re-analyses only the changed modules, and merges the updates with the existing documentation.

Two costs come with this path. The README warns that spawning Sonnet subagents can use significant tokens depending on codebase size, and that Haiku subagents can be used instead for a cheaper run at the cost of accuracy on complex codebases. The scanner also depends on tiktoken for token counting, installed with pip install tiktoken or uv pip install tiktoken.

Three licence statements, no releases, and a last push in May 2026

The licence information is inconsistent across the project, and that is worth sorting out before adoption rather than after.

The README ends with a License section that says MIT. The package.json declares a different licence, Apache-2.0, alongside the package name @kingbootoshi/cartographer and version 0.1.0. The repository's own licence field is listed as unknown. Three sources, two named licences.

The practical rule is the one that applies to any project: the LICENSE file in the repository is the text to read, and the README and the package.json field are summaries that can drift. Whichever it turns out to be, this is a question for whoever handles licence compliance in your organisation, not something to settle from a metadata field. The package.json files array does include LICENSE in the published files, so the text does travel with the package.

On releases, the repository has no GitHub releases at all. The package version is 0.1.0, which tells you the project is early, and there is no tag to pin to. The .evals/ directory and the docs/reports output mentioned in the eval section are how changes are tracked instead.

The repository is not archived and the last push was on 2026-05-13, which is more than six months ago, so treat the project as one that is not currently receiving regular updates. For a tool that an agent depends on in an automated loop, that stability question is the one to answer first: read the commit history since that date, and if the graph format or the command names have moved on, pin to a commit you have verified rather than tracking main.

Editorial conclusion

Cartographer suits teams that run coding agents against large repositories and want a measurable, checkable answer to the question of whether an agent actually consulted the codebase before it edited, since the graph, the removal ledgers and the notes are all reviewable artefacts on disk. It does not suit a team that wants a single document describing the architecture, because the legacy plugin path is documented as separate from the v2 CLI and the map output has been superseded by briefs and notes. Before adopting, run the index command on one real service and open the resulting CODEBASE_MAP.md and graph.sqlite yourself, decide whether the licence statement in the README or the one in package.json is the one your organisation will act on, and note that the last push was on 2026-05-13 with no GitHub releases published.

Frequently asked questions

Official sources

1. Issues
2. kingbootoshi/cartographer on GitHub
3. README