The same engine from a shell.

At a glance

Fourteen commands in four groups: looking at what you have, mapping a session, judging a version, and keeping the install healthy. Each one links to its full entry below.

Windows: the same commands work in PowerShell, cmd and Git Bash. If cartographer is not found, open a new terminal so the PATH change takes effect.

Looking at what you have

Four commands that change nothing. They show you the projects, sessions and maps Cartographer already knows about, in a browser or in the terminal.

cartographer serve

Opens the dashboard: your profile, recent sessions with a Map this session button, projects, maps, outcomes and completion. It binds to 127.0.0.1 and refuses requests from anywhere else, so nothing is reachable from the network. Every button that changes something carries a per-run token, so a page open in another tab cannot trigger it.

• --open opens your browser on the dashboard as soon as it is up.

When to use it. When you want to see what has been mapped, pick a session to map by hand, or read a replay without remembering a project name. If you would rather click than type, this is the only command you need to learn.

cartographer open

Renders and opens the replay for a project without going through the dashboard. Name no project and it opens the newest one.

• [project] is optional; the newest project is the default.

When to use it. The quickest route from a terminal to the story of a build. Pair it with projects when you have forgotten what a project is called.

cartographer sessions

Lists the sessions Cartographer can see. A tick marks the ones already mapped, so you can see at a glance what is still unmapped. Each line carries the session id you would pass to wrap.

• --all lists every agent's sessions, not only the current repo's.

When to use it. Before a backfill, or when you want to map one specific older session and need its id.

cartographer projects

Lists everything Cartographer knows: each project, its sessions, its declared versions and goals, and the appraisals that closed them. It takes no options.

When to use it. An inventory, when you want to see the shape of the work across repos, or to check which versions still have no appraisal.

Mapping a session

A map is written in two steps. Cartographer digests the transcript into a brief, and the agent that was in the session follows the brief to write the map. These five commands cover the brief, the filing, the catch-up for old sessions, and the rebuild of a replay.

cartographer wrap

Digests a session's transcript into a timeline with a reading of every prompt, then writes the brief the agent uses to write the map. This is what the /wrap command in Claude Code runs before Claude does the writing. With no options it takes the latest session of the repo you are in.

• --session id wraps an older session instead of the latest one. Get the id from sessions.
• --force redoes a session that already has a brief.
• --run also maps it with the agent's headless CLI, with no human in the loop.

When to use it. At the end of a session, or from a script that maps sessions automatically. If you installed with --auto, Claude Code runs it for you when a session ends.

cartographer save

Takes a map or appraisal file the agent has written, validates it against the rules, redacts secrets, files it under the project, and renders the replay. This is what Claude runs at the end of /wrap. The rules are the ones described on the How it works page: every move must cite the timeline items it rests on, "what it meant" has to name a technical implication, and praise words are rejected.

• --check only validates, and writes nothing. Useful when you are editing a map by hand and want to know whether it would be accepted.

When to use it. You rarely run it yourself. It is the last step of every wrap and every completion.

cartographer backfill

Prepares a brief for every session Claude Code still has on disk for a repo, so sessions from before you installed Cartographer can be mapped. This is what /cartographer-setup backfill runs.

• --cwd repo points at the repository whose sessions you want.
• --run maps them headlessly instead of only writing briefs.

When to use it. Once, after installing, to bring the history in. Retrospective maps read a little flatter than live ones, because nobody was there to be corrected.

cartographer sweep

Finds sessions that have stopped and have no map, and maps them. It exists for agents that have no session-end event, and it is meant to be run on a schedule.

• --dry lists what would be mapped without mapping anything.

When to use it. From a scheduled job, when you want everything mapped without remembering to wrap. Run it with --dry first to see what it would pick up.

cartographer render

Regenerates the replay for a project from its filed maps. It also accepts map and appraisal files directly, for rendering one on its own.

• --project name names the project to render.
• --open opens the result in your browser.

When to use it. After an update, or when a replay looks stale. open renders before it opens, so you only need this one when you want the file without the browser.

Judging a version

Session maps are provisional. The outcome you wanted is only known when a version is done, so the verdict lives in these two commands: one to say what done means, one to say what actually happened.

cartographer goal

Records, in your words, what the current version of the repo is supposed to achieve. It is the source of truth for every map and for the appraisal: every session map is judged against it, and complete reads the result back against it.

• Takes one quoted sentence. Run it in the repo the version belongs to.

When to use it. Before you start a version, ideally. It is optional, and /complete will ask for it later if you never declared one. A goal written before the work is a better yardstick than one written after, because it has not yet been bent to fit the result.

cartographer complete

Marks a version as done, with the result and what actually happened, and writes the brief for the appraisal: what got you there, what it cost, what was carried into the result, how you prompted. Every appraisal item cites session and move ids, and praise words are rejected on save.

• --result is one of shipped, partial or abandoned.
• --actual is what actually happened, in your words.
• --run writes the appraisal headlessly instead of handing the brief to the agent in conversation.

When to use it. When a version ships, or when you abandon it. The verdict on the whole build lives here, because a session cannot judge itself. An abandoned version is worth completing too; the appraisal of a dead end is often the most useful one you get.

Setup and health

Three commands for the install itself: the profile that shapes how maps are written, the registration with your agent, and the check to run when something is off.

cartographer config

Shows or changes your profile and settings. The profile shapes every brief: whether moves are written in your words or in code terms, coaching on or off, which languages Cartographer knows you use. Settings live in ~/.cartographer and never leave your machine.

• show prints the current settings.
• set key value changes one.
• init runs the setup wizard again.

When to use it. When you want to change how maps are written without opening a conversation. /cartographer-setup does the same thing from inside Claude Code, and the dashboard has a form for it.

cartographer install

Registers Cartographer's commands with an agent. The one-line installer on the Install page runs this for you; rerun it after updating so the commands stay current.

• --agent claude-code is the only agent today. Codex and Cursor are coming soon.
• --auto turns on automatic wrapping at the end of every session.

When to use it. After the install line, and again after an update. Switching between manual and automatic wrapping later is a config change, not a reinstall.

cartographer doctor

Prints what Cartographer can see: its version, the home folder, whether wrapping is manual or automatic, which agents were found and how many sessions each has, and which headless runners are available. It takes no options and changes nothing.

When to use it. First thing to run when something does not work, and the output to paste when you write to support@codecartographer.dev.