Two minutes on your machine. Hosting is only needed if you publish Mapwright for others — and it fits in free tiers.
Python 3.10 or newer. No other dependencies.
pipx install mapwrightFrom the downloaded folder instead: pipx install ./mapwright-0.1.0. Then, in your project:
mapwright initmapwright open
init records the current state as step 0. History lives in ~/.mapwright, outside your repository. open starts the local daemon on 127.0.0.1:7979 and opens the map.
mapwright connect --list shows the agents on this machine and what is connected. Existing config files are merged, never replaced, and backed up first. Restart the agent afterwards.
mapwright connect claude-codeWrites .mcp.json and hooks in .claude/settings.local.json. Hooks report prompts, edits and turn ends, so steps close by themselves. All projects: add --scope user. Or install the plugin from the repository's marketplace: /plugin install mapwright.
mapwright connect cursorWrites .cursor/mcp.json. Restart Cursor or reload the window. All projects: --scope user (~/.cursor/mcp.json).
mapwright connect vscodeWrites .vscode/mcp.json for Copilot agent mode. Install the extension for the map beside your code:
code --install-extension mapwright-vscode-0.1.0.vsixmapwright connect windsurf --scope userWrites ~/.codeium/windsurf/mcp_config.json.
mapwright connect geminiWrites .gemini/settings.json.
mapwright connect codex --scope userAdds [mcp_servers.mapwright] to ~/.codex/config.toml.
mapwright connect opencodeAdds mcp.mapwright to opencode.json. For automatic steps, also copy integrations/opencode/mapwright.js into .opencode/plugin/.
mapwright connect --print anyPaste the JSON into the agent's MCP settings (Cline, Roo Code, Zed, JetBrains AI, Claude Desktop …). No MCP at all? Run mapwright watch in the project: changes are tracked from the files, steps close after a quiet period, and the agent can use the CLI (mapwright brief, mapwright step "…").
mapwright agents-md --file CLAUDE.md adds six lines of usage notes to your agent instructions. For agents that read Agent Skills, copy integrations/skills/mapwright/ into the agent's skills folder.VS Code, Cursor, Windsurf, VSCodium: install mapwright-vscode-0.1.0.vsix (Extensions view → … → Install from VSIX). Commands: Open Map, Record Step, Copy Agent Brief, Connect an Agent; a status bar item shows the step, pending changes, todos and problems. JetBrains: open the map in the IDE's built-in browser.
mapwright doctorThe Connect panel in the UI shows the same, with buttons to connect and disconnect each agent.
The MCP server is not hosted. It has to run next to the code it maps: each developer's agent starts mapwright mcp locally, so code never leaves the machine. What you host is the website (static files, about 5 MB including the live demo) and the packages.
| Host | Free tier (check current terms) | Verdict |
|---|---|---|
| Cloudflare Pages | Static requests and bandwidth not metered on the free plan; custom domain and HTTPS | recommended no bandwidth worries for the heavy demo page |
| GitHub Pages | Free for public repos; soft limits around 1 GB site and 100 GB/month | easiest if the repo is public; workflow included |
| Firebase Hosting | No-cost plan with storage and transfer quotas (on the order of 10 GB) | solid, best inside a Firebase project; firebase.json included; tighter transfer quota |
| Netlify · Vercel | credit-based free plan · Hobby (non-commercial) | fine alternatives |
python scripts/build_site.pyCopies the UI into web/app/ and records the demo bundle, so the live demo needs no server. Publish the web/ folder.
npx wrangler pages deploy web --project-name mapwright
Push to main; Settings → Pages → Source: GitHub Actions. .github/workflows/pages.yml does the rest.
cp .firebaserc.example .firebasercpython scripts/build_site.py && firebase deploy --only hosting
PyPI for pipx install mapwright (python -m build, twine upload dist/*); VS Code Marketplace and Open VSX for the extension (vsce publish, ovsx publish); your GitHub repository as the Claude Code plugin marketplace. All free.
mapwright downmapwright disconnect claude-codepipx uninstall mapwright && rm -rf ~/.mapwright