mappamind

---

As agents write more of the code, your job shifts from author to supervisor — and supervision is where the mental model breaks. You didn't write the change, so you can't feel what moved. A 40-file agent diff is unreadable as a line-diff.

Mappamind builds an evidence-grounded picture of your codebase's behavior, flow, and architecture. When an agent session shifts it, you get a before/after picture at the accept moment: an alarm that draws. Agent dashboards render text. Mappamind is the picture they are missing.

Why Mappamind

Every claim on the card is grounded — it cites a real code fact or it gets dropped. The model cannot invent an endpoint or a dependency; both ends of every edge come from facts in your code. That is what lets you accept or reject on the picture: it is exactly correct, never a plausible lie about your architecture.

• At the accept moment, not at PR time. The card fires from the agent-session boundary (a Stop hook), in-session, while the change is still in your hands.
• Bounded by the change, not the repo. A code graph shrinks the work to the affected slice, so cost and latency track the diff, not the codebase size.
• No false alarms. A comment or leaf-only change folds as cosmetic and never rings.
• Self-contained output. Cards and the Studio are a single HTML file: no server, no <script>, no external assets. Open offline, share as one file.

What You Get

Mappamind writes one Studio file during setup, then adds shift cards when agent sessions change code:

.mappamind/
├── index.html                 # Studio: mesh, shifts, capabilities, contracts
└── shift/
    ├── latest.html            # latest non-cosmetic shift card
    └── <timestamp>.html       # archived cards linked from the Studio

The durable baseline and channel cache live beside these files under .mappamind/state/. See Storage and privacy.

Install

npm i -g mappamind-cli

This installs the mappamind command. (The package is published as mappamind-cli; the command you run is mappamind.)

Prerequisite: a model CLI on your PATH — Claude Code (claude) or Codex (codex). Mappamind shells out to the host you choose for grounded baseline synthesis and shift narration; no API key required.

Trying it without installing? npx -p mappamind-cli mappamind status <repo> works for a quick look, but the lifecycle hooks invoke the bare mappamind binary, so hooks need the global install above.

Quickstart

Five minutes from install to your first card.

# 1. Point Mappamind at a repo (or a parent folder of repos)
mappamind status .

# 2. Build the grounded baseline — the "before" picture
mappamind setup . --host claude --yes   # or: --host codex

# 3. Wire lifecycle hooks into supported agents
mappamind hooks --install

# 4. Run a normal agent session. When it ends, the Stop hook renders
#    the before/after card to .mappamind/shift/latest.html and opens it —
#    so you can decide whether to accept the change in your agent.

mappamind setup makes real model calls to synthesize grounded capabilities and adjudicate candidate channels, so it requires an explicit model host. If the selected host fails, setup stops without writing a baseline. On a small-to-medium repo that is usually seconds; larger repos cost more on first run. The CLI prints a progress estimate up front.