Docs

Every command, the MCP tools agents use, the settings, and why the protocol is shaped the way it is. Setup and hosting: Setup & deploy.

Commands

mw is a short alias for mapwright. Every command has --help. Commands that act on a project use the

current folder (or --path DIR).

Start and stop

CommandWhat it does
mapwright init [--connect AGENT] [--agents-md [FILE]]Track this project; the current state becomes step 0
mapwright open [--print] [--json]Open the map in the browser (starts the daemon if needed)
mapwright up [-d] [--no-watch] · mapwright downStart (foreground or background) or stop the daemon
mapwright watchTrack from the files alone, without the daemon or any agent integration
mapwright doctorCheck the setup
mapwright guideQuick reference

Agents

CommandWhat it does
mapwright connect --listAgents found on this machine and what is connected
mapwright connect AGENT [--scope project|user]Write the agent's MCP config (and hooks for Claude Code)
mapwright connect --print AGENTPrint the config to paste by hand
mapwright disconnect AGENT [--scope …]Remove it again
mapwright agents-md [--file AGENTS.md|CLAUDE.md|GEMINI.md|.cursorrules]Add six lines of usage notes for agents
mapwright mcp [--root DIR]The MCP server on stdio (agents start this)
mapwright hook AGENTHook entry point (agents call this with JSON on stdin)

Agents: claude-code, cursor, vscode, windsurf, opencode, codex, gemini, claude-desktop;

print-only: cline, zed, jetbrains, any.

While the agent works

CommandWhat it does
mapwright status [--json]Current step, pending changes, todos, problems
mapwright stepsEvery step with its changes and design delta
mapwright changes [--step N] [--diff]File changes since the last step, or in step N
mapwright step "TITLE" [--intent "WHY"]Close a step yourself
mapwright problemsClaims, notes, links, todos and step titles that do not check out
mapwright todo add TEXT · todo done ID --evidence SYMBOL · todo drop ID · todo listThe plan

For agents (also available as MCP tools)

CommandMCP toolWhat it does
mapwright brief [--budget N] [--focus PATH]mapThe map as compact text
mapwright find QUERYfindLocate symbols
mapwright symbol NAMEsymbolCallers, callees, tables, routes, history
mapwright step "TITLE"stepRecord a step
mapwright todo …todoPlan items, verified on done
mapwright claim CONCEPT SYMBOL [--note …]claimTag a mechanism; checked against the code
mapwright note SYMBOL ROLE…noteOne-line role, shown on the map
mapwright link FROM TO [--label …]linkA relation the code cannot show
mapwright catalogcatalogConcept ids

Diagrams and export

CommandWhat it does
mapwright diagram architecture|files|classes|data|cloud|processes|calls|concepts [--step N] [--focus X]Print a diagram as Mermaid
mapwright flow FUNCTIONFlowchart of one function
mapwright export -o DIRMAP.md (renders on GitHub) + every diagram + steps and verification as JSON

Settings

mapwright settings lists them; mapwright settings KEY VALUE changes one (also in the UI: Settings).

SettingDefaultMeaning
auto_stepturnturn: close a step at each agent turn end (hooks) · idle: after a quiet period · off
idle_seconds60Quiet period for idle (and for agents without hooks)
watch_interval2.0Seconds between scans while the daemon runs
brief_budget2400Characters in map / brief (about 600 tokens)
max_files · ignore5000 · []Size cap and extra folders to skip
redacttrueRedact secrets in code shown in the UI
theme · font_sizedark · 13Appearance

Environment: MAPWRIGHT_HOME (default ~/.mapwright), MAPWRIGHT_PORT (default 7979), MAPWRIGHT_ROOT (project for mcp).

Agent protocol

What an agent does with Mapwright, and why each part is shaped the way it is.

The loop

  1. Start of a task: call map. Read structure from it instead of listing directories and opening files.
  2. Plan: todo add for each part.
  3. Before changing a function: symbol NAME to see its callers, callees and tables. Open the file only to edit.
  4. After each meaningful change: step with a short title of what was done.
  5. When a part is finished: todo done ID with the symbol or file you changed as evidence.
  6. When you implement a mechanism (cache, retry, queue, auth …): claim CONCEPT SYMBOL.
  7. Optional: note a module's role; link two symbols the code does not connect directly.

With hooks (Claude Code, opencode), turn ends close a step even if the agent forgets step 4.

Why it is cheap

flowcharts are built from the code by Mapwright.

Why it cannot be gamed

The agent saysMapwright checks
a step titleThe changed files are computed. Titles that mention tests, migrations, routes, tables, docs or infrastructure are checked against what actually changed.
a todo is doneThe evidence must exist and must have changed after the todo was added.
a symbol implements a conceptThe concept's signals must appear in that symbol's code (decorators included). Only a module-level import counts as "weak".
a note or linkThe symbols must exist; when they disappear the note or link is marked stale.

MCP details

Hook events

mapwright hook AGENT reads one JSON object on stdin and always exits 0 without output.

hook_event_nameRecorded
UserPromptSubmit (prompt)the prompt, redacted, up to 300 characters
PostToolUse (tool_name, tool_input)the tool and the files it named
Stop / SessionEnda turn end; closes a step if files changed and auto_step allows