Setup & deploy

Two minutes on your machine. Hosting is only needed if you publish Mapwright for others — and it fits in free tiers.

1. Install

Python 3.10 or newer. No other dependencies.

pipx install mapwright

From the downloaded folder instead: pipx install ./mapwright-0.1.0. Then, in your project:

mapwright init
mapwright 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.

2. Connect your agent

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-code

Writes .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 cursor

Writes .cursor/mcp.json. Restart Cursor or reload the window. All projects: --scope user (~/.cursor/mcp.json).

mapwright connect vscode

Writes .vscode/mcp.json for Copilot agent mode. Install the extension for the map beside your code:

code --install-extension mapwright-vscode-0.1.0.vsix
mapwright connect windsurf --scope user

Writes ~/.codeium/windsurf/mcp_config.json.

mapwright connect gemini

Writes .gemini/settings.json.

mapwright connect codex --scope user

Adds [mcp_servers.mapwright] to ~/.codex/config.toml.

mapwright connect opencode

Adds mcp.mapwright to opencode.json. For automatic steps, also copy integrations/opencode/mapwright.js into .opencode/plugin/.

mapwright connect --print any

Paste 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 "…").

Optional: 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.

3. Editor extension (optional)

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.

4. Check

mapwright doctor

The Connect panel in the UI shows the same, with buttons to connect and disconnect each agent.

Deploy plan (free tier)

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.

HostFree tier (check current terms)Verdict
Cloudflare PagesStatic requests and bandwidth not metered on the free plan; custom domain and HTTPSrecommended no bandwidth worries for the heavy demo page
GitHub PagesFree for public repos; soft limits around 1 GB site and 100 GB/montheasiest if the repo is public; workflow included
Firebase HostingNo-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 · Vercelcredit-based free plan · Hobby (non-commercial)fine alternatives

Build the site

python scripts/build_site.py

Copies the UI into web/app/ and records the demo bundle, so the live demo needs no server. Publish the web/ folder.

Cloudflare Pages

npx wrangler pages deploy web --project-name mapwright

GitHub Pages

Push to main; Settings → Pages → Source: GitHub Actions. .github/workflows/pages.yml does the rest.

Firebase Hosting

cp .firebaserc.example .firebaserc
python scripts/build_site.py && firebase deploy --only hosting

Packages

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.

Stop & remove

mapwright down
mapwright disconnect claude-code
pipx uninstall mapwright && rm -rf ~/.mapwright