Step 1 · Claude Code
Skip this if you already type claude in a terminal. Cartographer reads the history Claude Code keeps, so Claude Code has to be there first.
Then open a new terminal, type claude --version to check it is there, go to a project folder, type claude and press Enter: a browser window opens to sign in (a Claude subscription or an API key). claude doctor checks the install; claude update updates it. Windows: install Git for Windows too (winget install Git.Git); it gives Claude Code its Bash tool and gives Cartographer Git Bash. Other ways in: brew install --cask claude-code, winget install Anthropic.ClaudeCode, or npm install -g @anthropic-ai/claude-code with Node 22+. The official steps live at code.claude.com/docs.
Step 2 · Cartographer
If you don't live in a terminal
- Open a terminal. Mac: press ⌘ Space, type Terminal, Enter. Windows: press the Windows key, type PowerShell, Enter. A window with a blinking cursor appears.
- Paste the line for your system and press Enter. It prints what it is doing. Thirty seconds, no questions. If it says Python is missing: on a Mac run xcode-select --install; on Windows run winget install Python.Python.3.12; then open a new terminal and paste the line again.
- Open your dashboard. Type cartographer serve --open and press Enter. A page opens in your browser. Only your computer can see it.
- Answer six questions. How comfortable you are with code, how experienced with prompting, what the map should sound like. This decides how Cartographer speaks to you. You can change it any time.
- Work in Claude Code as usual. Cartographer does nothing during the session.
- At the end of a session, type /wrap. Claude writes the map and tells you where the replay is. Come back to the dashboard, or type cartographer open, to watch it.
What the script does, exactly
- Checks for python3 3.9+. Nothing else is required. No pip, no venv, no npm.
- Downloads cartographer.tar.gz from this site (built from main on every deploy), falling back to git clone.
- Runs bin/cartographer install --agent claude-code. That copies the checkout to ~/.cartographer/app, symlinks ~/.local/bin/cartographer, and copies the skills to ~/.claude/skills/ (wrap, replay, complete, cartographer-setup).
- Touches ~/.claude/settings.json only with --auto, adding a SessionEnd hook that maps each session when it ends. Default is manual.
- Tells you if ~/.local/bin is not on your PATH, with the line to add.
- Windows: install.ps1 does the same with py or python, unpacks cartographer.zip, writes cartographer.cmd (PowerShell, cmd) and a shim for Git Bash (which Claude Code uses) into ~\.local\bin, and adds that folder to your user PATH. Hooks are registered as "python.exe" "…/bin/cartographer" hook claude-code, so they run without a Unix shell.
Manual install
git clone https://github.com/situatedstrategies/cartographer && cd cartographer
./bin/cartographer install --agent all # or --agent claude-code | cursor | codex; --auto for hooks
cartographer config init # or: cartographer serve --open
cartographer doctor # what is installed, where, and what it found
Update
Run the install line again. It replaces ~/.cartographer/app and the skills; your maps and config stay.
Uninstall
rm -rf ~/.cartographer ~/.local/bin/cartographer ~/.claude/skills/{wrap,replay,complete,cartographer-setup}
# Windows (PowerShell): Remove-Item -Recurse ~\.cartographer, ~\.local\bin\cartographer*, ~\.claude\skills\wrap, ~\.claude\skills\replay, ~\.claude\skills\complete, ~\.claude\skills\cartographer-setup
# and, if you used --auto, remove the cartographer SessionEnd hook from ~/.claude/settings.json