mapwright-agent 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. mapwright_agent-0.2.0/.gitignore +9 -0
  2. mapwright_agent-0.2.0/CHANGELOG.md +30 -0
  3. mapwright_agent-0.2.0/LICENSE +21 -0
  4. mapwright_agent-0.2.0/PKG-INFO +179 -0
  5. mapwright_agent-0.2.0/README.md +152 -0
  6. mapwright_agent-0.2.0/docs/AGENT_PROTOCOL.md +48 -0
  7. mapwright_agent-0.2.0/docs/ARCHITECTURE.md +50 -0
  8. mapwright_agent-0.2.0/docs/COMMANDS.md +85 -0
  9. mapwright_agent-0.2.0/docs/RELEASING.md +41 -0
  10. mapwright_agent-0.2.0/docs/ROADMAP.md +49 -0
  11. mapwright_agent-0.2.0/docs/SETUP.md +273 -0
  12. mapwright_agent-0.2.0/docs/img/architecture.png +0 -0
  13. mapwright_agent-0.2.0/docs/img/cloud.png +0 -0
  14. mapwright_agent-0.2.0/docs/img/concepts.png +0 -0
  15. mapwright_agent-0.2.0/docs/img/data.png +0 -0
  16. mapwright_agent-0.2.0/docs/img/light.png +0 -0
  17. mapwright_agent-0.2.0/docs/img/logic.png +0 -0
  18. mapwright_agent-0.2.0/docs/img/overview.png +0 -0
  19. mapwright_agent-0.2.0/docs/img/processes.png +0 -0
  20. mapwright_agent-0.2.0/docs/img/settings.png +0 -0
  21. mapwright_agent-0.2.0/docs/img/setup.png +0 -0
  22. mapwright_agent-0.2.0/docs/img/timeline.png +0 -0
  23. mapwright_agent-0.2.0/integrations/claude-code/.claude-plugin/plugin.json +8 -0
  24. mapwright_agent-0.2.0/integrations/claude-code/.mcp.json +5 -0
  25. mapwright_agent-0.2.0/integrations/claude-code/hooks/hooks.json +7 -0
  26. mapwright_agent-0.2.0/integrations/claude-code/skills/mapwright/SKILL.md +45 -0
  27. mapwright_agent-0.2.0/integrations/opencode/mapwright.js +30 -0
  28. mapwright_agent-0.2.0/integrations/skills/mapwright/SKILL.md +45 -0
  29. mapwright_agent-0.2.0/integrations/vscode/LICENSE +21 -0
  30. mapwright_agent-0.2.0/integrations/vscode/README.md +22 -0
  31. mapwright_agent-0.2.0/integrations/vscode/extension.js +91 -0
  32. mapwright_agent-0.2.0/integrations/vscode/icon.png +0 -0
  33. mapwright_agent-0.2.0/integrations/vscode/mapwright-vscode-0.1.0.vsix +0 -0
  34. mapwright_agent-0.2.0/integrations/vscode/package.json +103 -0
  35. mapwright_agent-0.2.0/pyproject.toml +50 -0
  36. mapwright_agent-0.2.0/scripts/build_site.py +117 -0
  37. mapwright_agent-0.2.0/scripts/demo_session.py +444 -0
  38. mapwright_agent-0.2.0/src/mapwright/__init__.py +3 -0
  39. mapwright_agent-0.2.0/src/mapwright/__main__.py +3 -0
  40. mapwright_agent-0.2.0/src/mapwright/analyze.py +809 -0
  41. mapwright_agent-0.2.0/src/mapwright/brief.py +208 -0
  42. mapwright_agent-0.2.0/src/mapwright/cli.py +596 -0
  43. mapwright_agent-0.2.0/src/mapwright/concepts.py +190 -0
  44. mapwright_agent-0.2.0/src/mapwright/config.py +204 -0
  45. mapwright_agent-0.2.0/src/mapwright/connect.py +337 -0
  46. mapwright_agent-0.2.0/src/mapwright/export.py +42 -0
  47. mapwright_agent-0.2.0/src/mapwright/firestore.py +168 -0
  48. mapwright_agent-0.2.0/src/mapwright/flow.py +238 -0
  49. mapwright_agent-0.2.0/src/mapwright/hooks.py +111 -0
  50. mapwright_agent-0.2.0/src/mapwright/ignore.py +248 -0
  51. mapwright_agent-0.2.0/src/mapwright/infra.py +253 -0
  52. mapwright_agent-0.2.0/src/mapwright/mcp.py +153 -0
  53. mapwright_agent-0.2.0/src/mapwright/noise.py +80 -0
  54. mapwright_agent-0.2.0/src/mapwright/redact.py +39 -0
  55. mapwright_agent-0.2.0/src/mapwright/render.py +428 -0
  56. mapwright_agent-0.2.0/src/mapwright/routes_js.py +282 -0
  57. mapwright_agent-0.2.0/src/mapwright/server.py +388 -0
  58. mapwright_agent-0.2.0/src/mapwright/titles.py +111 -0
  59. mapwright_agent-0.2.0/src/mapwright/track.py +715 -0
  60. mapwright_agent-0.2.0/src/mapwright/ui/app.css +277 -0
  61. mapwright_agent-0.2.0/src/mapwright/ui/app.js +1025 -0
  62. mapwright_agent-0.2.0/src/mapwright/ui/icons.svg +73 -0
  63. mapwright_agent-0.2.0/src/mapwright/ui/index.html +35 -0
  64. mapwright_agent-0.2.0/src/mapwright/ui/mark.svg +1 -0
  65. mapwright_agent-0.2.0/src/mapwright/ui/vendor/mermaid.LICENSE +21 -0
  66. mapwright_agent-0.2.0/src/mapwright/ui/vendor/mermaid.min.js +2029 -0
  67. mapwright_agent-0.2.0/tests/conftest.py +20 -0
  68. mapwright_agent-0.2.0/tests/test_analysis.py +128 -0
  69. mapwright_agent-0.2.0/tests/test_autostep.py +125 -0
  70. mapwright_agent-0.2.0/tests/test_disconnect.py +104 -0
  71. mapwright_agent-0.2.0/tests/test_firestore.py +75 -0
  72. mapwright_agent-0.2.0/tests/test_ignore.py +157 -0
  73. mapwright_agent-0.2.0/tests/test_local_home.py +150 -0
  74. mapwright_agent-0.2.0/tests/test_release.py +18 -0
  75. mapwright_agent-0.2.0/tests/test_routes_js.py +69 -0
  76. mapwright_agent-0.2.0/tests/test_system_view.py +20 -0
  77. mapwright_agent-0.2.0/tests/test_titles.py +43 -0
  78. mapwright_agent-0.2.0/tests/test_tracking.py +227 -0
  79. mapwright_agent-0.2.0/tests/test_ui_auth.py +56 -0
  80. mapwright_agent-0.2.0/tests/test_web_origin.py +62 -0
@@ -0,0 +1,9 @@
1
+ __pycache__/
2
+ *.pyc
3
+ *.egg-info/
4
+ .pytest_cache/
5
+ dist/
6
+ build/
7
+ .venv/
8
+ web/app/
9
+ node_modules/
@@ -0,0 +1,30 @@
1
+ # Changelog
2
+
3
+ ## 0.2.0
4
+
5
+ - PyPI release pipeline (trusted publishing, tag-driven, TestPyPI rehearsal) under the name `mapwright-agent`; version is single-sourced in `src/mapwright/__init__.py`; timeline markers centred on their line.
6
+
7
+ - First-run UI: clear "Unauthorised" and "daemon not running" states, paste-link/token box, token remembered in the browser, "Forget token"; consistent control sizes and alignment.
8
+ - Project-local homes: `mapwright init --local` / `--home DIR`, discovery via `.mapwright/home.json`, `MAPWRIGHT_HOME` written into generated MCP entries and Claude Code hook commands; `/v1/ping` reports the daemon's home.
9
+ - Respect `.gitignore` by default (`respect_gitignore`), gitignore-style patterns in `ignore`, `max_files` now honoured and truncation reported (`init`, `doctor`, `state`), ignore suggestions on `init` (`--apply-ignore`); scans are deterministic and share no global state.
10
+ - Auto steps get short clean titles instead of raw prompts, skip noise-only changes (lockfiles, generated output), ignore subagent and overlapping-session stops; read-only Bash calls are no longer journaled.
11
+ - Detect React Router routes (config arrays, JSX, lazy groups), Firestore/Storage security rules and collection usage as data collections, zod schemas as entities, and tag React components and hooks.
12
+ - Hosted website support: `web_origins` allowlist with CORS and private-network preflight in the daemon, `mapwright open --web`, and a UI that talks to a loopback daemon when served from a hosted site (demo stays the default until a token link is used).
13
+ - System view (default tab): an abstract icon diagram of clients, interface, logic, data, outside services and platform built from the analysis; click a component to see its files, routes, tables and most complex functions in the Inspector; new and changed components are marked.
14
+ - `mapwright disconnect` deletes config files (and empty tool folders) it leaves empty.
15
+
16
+ ## 0.1.0
17
+
18
+ First release.
19
+
20
+ - Static analysis of Python, JS/TS, SQL (including SQL in code strings) and Prisma: modules, layers, classes,
21
+ functions, call graph, routes, tables, algorithm hints.
22
+ - 29-concept catalog with detectors and verified claims.
23
+ - Infrastructure from Docker, Compose, Terraform, Kubernetes, serverless, Procfile, CI, hosting configs, env files and SDK imports.
24
+ - Step store with every file version, computed changes and design deltas; automatic steps at turn ends (hooks) or after a quiet period.
25
+ - Verification of step titles, todos, claims, notes and links.
26
+ - MCP server (9 tools), hook client, config writers for 8 agents plus paste-in snippets.
27
+ - IDE-style UI (dark/light): overview, architecture, files, classes, data, cloud, processes, logic with flowcharts,
28
+ concepts, timeline, code and diff viewers, inspector, search everywhere, settings, connect panel.
29
+ - VS Code extension, Claude Code plugin, opencode plugin, Agent Skill.
30
+ - Website with a live demo; setup and free-tier deploy guide.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Fencewright contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,179 @@
1
+ Metadata-Version: 2.5
2
+ Name: mapwright-agent
3
+ Version: 0.2.0
4
+ Summary: A live map of what your coding agent is building: structure, architecture, data, cloud, logic and every step, readable by the agent for a fraction of the tokens.
5
+ Project-URL: Homepage, https://mapwright.pages.dev
6
+ Project-URL: Repository, https://github.com/1mystic/Mapwright
7
+ Project-URL: Changelog, https://github.com/1mystic/Mapwright/blob/main/CHANGELOG.md
8
+ Project-URL: Issues, https://github.com/1mystic/Mapwright/issues
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: ai-agents,architecture,claude-code,code-map,copilot,cursor,diagrams,mcp,observability
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Environment :: Web Environment
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Topic :: Software Development :: Documentation
20
+ Classifier: Topic :: Software Development :: Quality Assurance
21
+ Requires-Python: >=3.10
22
+ Provides-Extra: dev
23
+ Requires-Dist: pytest>=8; extra == 'dev'
24
+ Provides-Extra: yaml
25
+ Requires-Dist: pyyaml>=6; extra == 'yaml'
26
+ Description-Content-Type: text/markdown
27
+
28
+ <p align="center"><img src="src/mapwright/ui/mark.svg" width="56" alt=""></p>
29
+ <h1 align="center">Mapwright</h1>
30
+ <p align="center"><b>A live map of what your coding agent is building.</b><br>
31
+ Structure, architecture, data model, cloud, API flows, logic and every step, drawn from the code as the agent writes it,<br>
32
+ and readable by the agent itself for a fraction of the tokens.</p>
33
+
34
+ <p align="center">
35
+ <a href="#quickstart">Quickstart</a> · <a href="#what-you-see">What you see</a> · <a href="#how-it-keeps-token-cost-low">Token cost</a> ·
36
+ <a href="#no-cheating">Verification</a> · <a href="#works-with">Works with</a> · <a href="docs/SETUP.md">Setup &amp; deploy guide</a> · <a href="docs/COMMANDS.md">Commands</a>
37
+ </p>
38
+
39
+ <p align="center"><img src="docs/img/overview.png" alt="Mapwright overview of a project built by an agent: counts, latest step, layers, mechanisms, entry points" width="100%"></p>
40
+
41
+ ## Why
42
+
43
+ When an agent builds a project, you get files. You do not get the picture: how the pieces fit, what
44
+ talks to the database, which mechanisms it used, what changed in each turn, and whether what it says
45
+ it did is what it actually did. And the agent itself spends a large share of its tokens rediscovering
46
+ the same structure by listing directories and reading files.
47
+
48
+ Mapwright watches the code, not the agent's description of it. It builds the map with static
49
+ analysis, keeps a version of every file at each step, and gives the agent a compact text view of the
50
+ map so it can stop exploring. The agent's only job is to say when a step is done and what the plan
51
+ is; everything else is computed, and everything it claims is checked.
52
+
53
+ ## Quickstart
54
+
55
+ ```bash
56
+ pipx install mapwright-agent # zero dependencies, Python 3.10+ (command: mapwright)
57
+ # or straight from GitHub: pipx install git+https://github.com/1mystic/Mapwright.git
58
+ cd your-project
59
+ mapwright init --connect claude-code # baseline + MCP server + hooks for this project
60
+ mapwright open # the map in your browser
61
+ ```
62
+
63
+ Then work with your agent as usual. Other agents: `mapwright connect --list`. Full guide, including the
64
+ VS Code extension and hosting the website for free: [docs/SETUP.md](docs/SETUP.md).
65
+
66
+ ## What you see
67
+
68
+ An IDE-style interface (dark and light), live while the agent works, with every view also available
69
+ at any earlier step:
70
+
71
+ | View | Shows | Built from |
72
+ |---|---|---|
73
+ | **System** | The whole system as one abstract, icon-based picture (clients → interface → logic → data → outside services, plus platform); click a component for what is inside it | layers, routes, tables, infrastructure |
74
+ | **Overview** | Counts, what the agent just did, layers, mechanisms, entry points, infrastructure, hotspots, plan, verification | everything below |
75
+ | **Architecture** | Modules grouped into layers (interface, services, data, integrations, UI …), imports, external packages | Python `ast`, JS/TS imports |
76
+ | **Files** | How the project is organised, with added and changed files marked | the file tree |
77
+ | **Classes** | Classes, attributes, methods, inheritance and "uses" links | Python, JS/TS |
78
+ | **Data** | Tables, columns, keys and relations | SQL (also inside code strings), SQLAlchemy, Django, Prisma, zod schemas, Firestore/Storage collections with their security rules |
79
+ | **Cloud** | Containers, services, databases, caches, queues, buckets, functions, CI, external APIs | Dockerfile, compose, Terraform, Kubernetes, serverless, CI, `.env.example`, SDK imports |
80
+ | **Processes** | Each HTTP route → handler → the functions it calls → the tables they touch | routes (FastAPI, Flask, Express, Next.js), call graph |
81
+ | **Logic** | Every function by complexity, with algorithm hints, and a flowchart of its control flow | Python `ast` (JS/TS: outline) |
82
+ | **Concepts** | Mechanisms in use (29 kinds: caching, retries, queues, auth, rate limiting, ORM, LLM calls …) with evidence in the code | the concept catalog |
83
+ | **Timeline** | Every step: what was asked, files changed with diffs, design changes, verification | the step store |
84
+
85
+ Click any box to inspect it; double-click to open the code, the flowchart or the call graph. Search
86
+ everything with <kbd>⇧</kbd><kbd>⇧</kbd>. The bottom panel holds steps, todos, problems and the agent's activity.
87
+
88
+ <table>
89
+ <tr><td><img src="docs/img/architecture.png" alt="Architecture view: modules grouped into layers with imports and external packages"></td>
90
+ <td><img src="docs/img/logic.png" alt="Logic view: functions sorted by complexity and a flowchart of the selected function"></td></tr>
91
+ <tr><td><img src="docs/img/cloud.png" alt="Cloud view: compose services, Terraform resources, external APIs"></td>
92
+ <td><img src="docs/img/timeline.png" alt="Timeline view: each step with its changes, design delta and a verification warning"></td></tr>
93
+ </table>
94
+
95
+ ## How it keeps token cost low
96
+
97
+ The agent never draws a diagram, writes a summary or lists files. It uses a few small tools:
98
+
99
+ | Tool | The agent sends | It gets back |
100
+ |---|---|---|
101
+ | `map` | nothing (or a folder to expand) | The whole map in about 600 tokens: layers, modules and key symbols, routes, tables, infra, mechanisms, algorithms, open todos, recent steps. No source code. |
102
+ | `find` · `symbol` | a name | Where it is; its callers, callees, tables, routes and history. No source code. |
103
+ | `step` | a title, e.g. "Add refunds" | A receipt of what actually changed (files, lines, new and changed functions, classes, tables) |
104
+ | `todo` | the plan, then "done" with evidence | Whether the evidence really changed |
105
+ | `claim` · `note` · `link` | an id from the catalog and a symbol | Whether the code backs it up |
106
+
107
+ All nine tool definitions together are under 3,000 characters, because they are sent with every request.
108
+ The diagrams, icons, layouts and flowcharts are built by Mapwright from the code, so the agent spends
109
+ no output tokens on them.
110
+
111
+ ## No cheating
112
+
113
+ Nothing the agent says is taken at its word:
114
+
115
+ - **What changed in a step is computed** from the files, not reported by the agent.
116
+ - **A step title is checked** against the changes: "Add tests" with no test file changed is flagged.
117
+ - **A todo marked done needs evidence** (a symbol or file) that changed after the todo was added.
118
+ - **A claimed mechanism must be visible in the code** of the symbol it names (`retry-backoff` on a function
119
+ with no retry loop is "unverified").
120
+ - **Notes and links go stale** when the code they point at disappears.
121
+
122
+ Everything that does not check out appears under **Problems**, in the agent's own `map`, and in exports.
123
+
124
+ ## Validation
125
+
126
+ Measured on this release (Python 3.13, Linux):
127
+
128
+ | | |
129
+ |---|---|
130
+ | Real agent run | Claude Code 2.1.325, headless, two turns (85 agent turns in all) building a URL shortener from an empty folder, then adding rate limiting and a stats endpoint, with Mapwright connected through `mapwright init --connect claude-code`. Tool calls: `todo` 23, `step` 9, `claim` 8, `map` 3, `symbol` 1, `catalog` 1, against 26 file writes and edits and **1 file read**. Result: 9 steps with correct computed changes, 11 of 11 todos verified, 8 of 8 claims verified, 0 problems. |
131
+ | What the real run fixed | It surfaced two false alarms, both fixed in this release: tables created in SQL strings were missed (a step about tables was flagged), and camelCase names like `TokenBucketLimiter` did not count as evidence (4 honest claims showed as unverified). Stored warnings are re-checked with the current analysis, so the fixes apply to history too. |
132
+ | Scripted session | 7 turns building an order service; the deliberately dishonest 7th turn produced exactly 3 problems (wrong step title, unearned todo, unbacked claim) and nothing else. |
133
+ | Tests | 23 passing (analysis, flowcharts, infra, tracking, verification, MCP over stdio, hooks, config writers, daemon API, the full session). |
134
+ | Speed | First scan of an 84-file repository 0.8 s; a new process starts warm in 0.01 s (cached by content hash). |
135
+ | Size | No runtime dependencies. Wheel about 1 MB, mostly the bundled diagram renderer. |
136
+
137
+ ## Works with
138
+
139
+ | Agent / editor | How | Command |
140
+ |---|---|---|
141
+ | Claude Code | MCP server + hooks (prompts, edits, turn ends → automatic steps), or the plugin | `mapwright connect claude-code` |
142
+ | Cursor | MCP server | `mapwright connect cursor` |
143
+ | VS Code (Copilot agent mode) | MCP server, plus the extension for the map beside your code | `mapwright connect vscode` |
144
+ | Windsurf · Gemini CLI · Codex CLI · opencode · Claude Desktop | MCP server (opencode also has a plugin for automatic steps) | `mapwright connect <id>` |
145
+ | Cline · Roo · Zed · JetBrains AI | MCP config to paste | `mapwright connect --print <id>` |
146
+ | Anything else | File watching: steps close after a quiet period; the agent can use the CLI | `mapwright watch` |
147
+
148
+ For agents that support Agent Skills, `integrations/skills/mapwright/SKILL.md` teaches the workflow with
149
+ the MCP tools or, without MCP, the same through the shell.
150
+
151
+ ## Privacy
152
+
153
+ Everything runs on your machine. The daemon listens on `127.0.0.1` only and needs a token. Secret-looking
154
+ files (`.env`, keys, credentials) are tracked as "changed" but never read. Code shown in the UI and in diffs
155
+ is passed through redaction. Nothing is sent anywhere.
156
+
157
+ ## Limits
158
+
159
+ - Static analysis: dynamic imports, metaprogramming and tables created at runtime are not seen. Algorithm
160
+ hints are hints.
161
+ - Routes are found for FastAPI, Flask, Express-style routers, Next.js and React Router (config arrays, `<Route>` JSX, `lazyGroup`-style helpers; shown as `PAGE`), not for hand-written `http.server` handlers. Route arrays built dynamically or mounted under a layout in another file show only their own paths.
162
+ - Firestore and Cloud Storage rules (`firestore.rules`, `storage.rules`) and static `collection()`/`doc()` calls appear as `firestore:`/`storage:` collections with allowed operations; paths built at runtime, and Firestore use from Python, are not seen. SQL inside content strings (e.g. quiz text) can still be reported as tables.
163
+ - Structure is drawn for Python, JS/TS, SQL and Prisma. Other languages are tracked for changes but not drawn.
164
+ - JS/TS flowcharts are an outline (branches and calls in order), not a full parse.
165
+ - Steps close at turn ends only with hooks (Claude Code, opencode); elsewhere the agent calls `step` or a quiet period closes it.
166
+ - The VS Code extension was packaged and checked for syntax here, not exercised inside an editor.
167
+
168
+ ## Project layout
169
+
170
+ ```
171
+ src/mapwright/ analysis, tracking, MCP server, hooks, daemon, CLI, UI
172
+ integrations/ VS Code extension (.vsix included), Claude Code plugin, opencode plugin, Agent Skill
173
+ web/ website (landing, docs, setup) + scripts/build_site.py builds the live demo
174
+ docs/ SETUP (install, connect, deploy), COMMANDS, AGENT_PROTOCOL, ARCHITECTURE
175
+ scripts/ demo_session.py (scripted agent), build_site.py
176
+ tests/
177
+ ```
178
+
179
+ MIT licensed. The diagram renderer is [Mermaid](https://mermaid.js.org) 10.9.3 (MIT), bundled.
@@ -0,0 +1,152 @@
1
+ <p align="center"><img src="src/mapwright/ui/mark.svg" width="56" alt=""></p>
2
+ <h1 align="center">Mapwright</h1>
3
+ <p align="center"><b>A live map of what your coding agent is building.</b><br>
4
+ Structure, architecture, data model, cloud, API flows, logic and every step, drawn from the code as the agent writes it,<br>
5
+ and readable by the agent itself for a fraction of the tokens.</p>
6
+
7
+ <p align="center">
8
+ <a href="#quickstart">Quickstart</a> · <a href="#what-you-see">What you see</a> · <a href="#how-it-keeps-token-cost-low">Token cost</a> ·
9
+ <a href="#no-cheating">Verification</a> · <a href="#works-with">Works with</a> · <a href="docs/SETUP.md">Setup &amp; deploy guide</a> · <a href="docs/COMMANDS.md">Commands</a>
10
+ </p>
11
+
12
+ <p align="center"><img src="docs/img/overview.png" alt="Mapwright overview of a project built by an agent: counts, latest step, layers, mechanisms, entry points" width="100%"></p>
13
+
14
+ ## Why
15
+
16
+ When an agent builds a project, you get files. You do not get the picture: how the pieces fit, what
17
+ talks to the database, which mechanisms it used, what changed in each turn, and whether what it says
18
+ it did is what it actually did. And the agent itself spends a large share of its tokens rediscovering
19
+ the same structure by listing directories and reading files.
20
+
21
+ Mapwright watches the code, not the agent's description of it. It builds the map with static
22
+ analysis, keeps a version of every file at each step, and gives the agent a compact text view of the
23
+ map so it can stop exploring. The agent's only job is to say when a step is done and what the plan
24
+ is; everything else is computed, and everything it claims is checked.
25
+
26
+ ## Quickstart
27
+
28
+ ```bash
29
+ pipx install mapwright-agent # zero dependencies, Python 3.10+ (command: mapwright)
30
+ # or straight from GitHub: pipx install git+https://github.com/1mystic/Mapwright.git
31
+ cd your-project
32
+ mapwright init --connect claude-code # baseline + MCP server + hooks for this project
33
+ mapwright open # the map in your browser
34
+ ```
35
+
36
+ Then work with your agent as usual. Other agents: `mapwright connect --list`. Full guide, including the
37
+ VS Code extension and hosting the website for free: [docs/SETUP.md](docs/SETUP.md).
38
+
39
+ ## What you see
40
+
41
+ An IDE-style interface (dark and light), live while the agent works, with every view also available
42
+ at any earlier step:
43
+
44
+ | View | Shows | Built from |
45
+ |---|---|---|
46
+ | **System** | The whole system as one abstract, icon-based picture (clients → interface → logic → data → outside services, plus platform); click a component for what is inside it | layers, routes, tables, infrastructure |
47
+ | **Overview** | Counts, what the agent just did, layers, mechanisms, entry points, infrastructure, hotspots, plan, verification | everything below |
48
+ | **Architecture** | Modules grouped into layers (interface, services, data, integrations, UI …), imports, external packages | Python `ast`, JS/TS imports |
49
+ | **Files** | How the project is organised, with added and changed files marked | the file tree |
50
+ | **Classes** | Classes, attributes, methods, inheritance and "uses" links | Python, JS/TS |
51
+ | **Data** | Tables, columns, keys and relations | SQL (also inside code strings), SQLAlchemy, Django, Prisma, zod schemas, Firestore/Storage collections with their security rules |
52
+ | **Cloud** | Containers, services, databases, caches, queues, buckets, functions, CI, external APIs | Dockerfile, compose, Terraform, Kubernetes, serverless, CI, `.env.example`, SDK imports |
53
+ | **Processes** | Each HTTP route → handler → the functions it calls → the tables they touch | routes (FastAPI, Flask, Express, Next.js), call graph |
54
+ | **Logic** | Every function by complexity, with algorithm hints, and a flowchart of its control flow | Python `ast` (JS/TS: outline) |
55
+ | **Concepts** | Mechanisms in use (29 kinds: caching, retries, queues, auth, rate limiting, ORM, LLM calls …) with evidence in the code | the concept catalog |
56
+ | **Timeline** | Every step: what was asked, files changed with diffs, design changes, verification | the step store |
57
+
58
+ Click any box to inspect it; double-click to open the code, the flowchart or the call graph. Search
59
+ everything with <kbd>⇧</kbd><kbd>⇧</kbd>. The bottom panel holds steps, todos, problems and the agent's activity.
60
+
61
+ <table>
62
+ <tr><td><img src="docs/img/architecture.png" alt="Architecture view: modules grouped into layers with imports and external packages"></td>
63
+ <td><img src="docs/img/logic.png" alt="Logic view: functions sorted by complexity and a flowchart of the selected function"></td></tr>
64
+ <tr><td><img src="docs/img/cloud.png" alt="Cloud view: compose services, Terraform resources, external APIs"></td>
65
+ <td><img src="docs/img/timeline.png" alt="Timeline view: each step with its changes, design delta and a verification warning"></td></tr>
66
+ </table>
67
+
68
+ ## How it keeps token cost low
69
+
70
+ The agent never draws a diagram, writes a summary or lists files. It uses a few small tools:
71
+
72
+ | Tool | The agent sends | It gets back |
73
+ |---|---|---|
74
+ | `map` | nothing (or a folder to expand) | The whole map in about 600 tokens: layers, modules and key symbols, routes, tables, infra, mechanisms, algorithms, open todos, recent steps. No source code. |
75
+ | `find` · `symbol` | a name | Where it is; its callers, callees, tables, routes and history. No source code. |
76
+ | `step` | a title, e.g. "Add refunds" | A receipt of what actually changed (files, lines, new and changed functions, classes, tables) |
77
+ | `todo` | the plan, then "done" with evidence | Whether the evidence really changed |
78
+ | `claim` · `note` · `link` | an id from the catalog and a symbol | Whether the code backs it up |
79
+
80
+ All nine tool definitions together are under 3,000 characters, because they are sent with every request.
81
+ The diagrams, icons, layouts and flowcharts are built by Mapwright from the code, so the agent spends
82
+ no output tokens on them.
83
+
84
+ ## No cheating
85
+
86
+ Nothing the agent says is taken at its word:
87
+
88
+ - **What changed in a step is computed** from the files, not reported by the agent.
89
+ - **A step title is checked** against the changes: "Add tests" with no test file changed is flagged.
90
+ - **A todo marked done needs evidence** (a symbol or file) that changed after the todo was added.
91
+ - **A claimed mechanism must be visible in the code** of the symbol it names (`retry-backoff` on a function
92
+ with no retry loop is "unverified").
93
+ - **Notes and links go stale** when the code they point at disappears.
94
+
95
+ Everything that does not check out appears under **Problems**, in the agent's own `map`, and in exports.
96
+
97
+ ## Validation
98
+
99
+ Measured on this release (Python 3.13, Linux):
100
+
101
+ | | |
102
+ |---|---|
103
+ | Real agent run | Claude Code 2.1.325, headless, two turns (85 agent turns in all) building a URL shortener from an empty folder, then adding rate limiting and a stats endpoint, with Mapwright connected through `mapwright init --connect claude-code`. Tool calls: `todo` 23, `step` 9, `claim` 8, `map` 3, `symbol` 1, `catalog` 1, against 26 file writes and edits and **1 file read**. Result: 9 steps with correct computed changes, 11 of 11 todos verified, 8 of 8 claims verified, 0 problems. |
104
+ | What the real run fixed | It surfaced two false alarms, both fixed in this release: tables created in SQL strings were missed (a step about tables was flagged), and camelCase names like `TokenBucketLimiter` did not count as evidence (4 honest claims showed as unverified). Stored warnings are re-checked with the current analysis, so the fixes apply to history too. |
105
+ | Scripted session | 7 turns building an order service; the deliberately dishonest 7th turn produced exactly 3 problems (wrong step title, unearned todo, unbacked claim) and nothing else. |
106
+ | Tests | 23 passing (analysis, flowcharts, infra, tracking, verification, MCP over stdio, hooks, config writers, daemon API, the full session). |
107
+ | Speed | First scan of an 84-file repository 0.8 s; a new process starts warm in 0.01 s (cached by content hash). |
108
+ | Size | No runtime dependencies. Wheel about 1 MB, mostly the bundled diagram renderer. |
109
+
110
+ ## Works with
111
+
112
+ | Agent / editor | How | Command |
113
+ |---|---|---|
114
+ | Claude Code | MCP server + hooks (prompts, edits, turn ends → automatic steps), or the plugin | `mapwright connect claude-code` |
115
+ | Cursor | MCP server | `mapwright connect cursor` |
116
+ | VS Code (Copilot agent mode) | MCP server, plus the extension for the map beside your code | `mapwright connect vscode` |
117
+ | Windsurf · Gemini CLI · Codex CLI · opencode · Claude Desktop | MCP server (opencode also has a plugin for automatic steps) | `mapwright connect <id>` |
118
+ | Cline · Roo · Zed · JetBrains AI | MCP config to paste | `mapwright connect --print <id>` |
119
+ | Anything else | File watching: steps close after a quiet period; the agent can use the CLI | `mapwright watch` |
120
+
121
+ For agents that support Agent Skills, `integrations/skills/mapwright/SKILL.md` teaches the workflow with
122
+ the MCP tools or, without MCP, the same through the shell.
123
+
124
+ ## Privacy
125
+
126
+ Everything runs on your machine. The daemon listens on `127.0.0.1` only and needs a token. Secret-looking
127
+ files (`.env`, keys, credentials) are tracked as "changed" but never read. Code shown in the UI and in diffs
128
+ is passed through redaction. Nothing is sent anywhere.
129
+
130
+ ## Limits
131
+
132
+ - Static analysis: dynamic imports, metaprogramming and tables created at runtime are not seen. Algorithm
133
+ hints are hints.
134
+ - Routes are found for FastAPI, Flask, Express-style routers, Next.js and React Router (config arrays, `<Route>` JSX, `lazyGroup`-style helpers; shown as `PAGE`), not for hand-written `http.server` handlers. Route arrays built dynamically or mounted under a layout in another file show only their own paths.
135
+ - Firestore and Cloud Storage rules (`firestore.rules`, `storage.rules`) and static `collection()`/`doc()` calls appear as `firestore:`/`storage:` collections with allowed operations; paths built at runtime, and Firestore use from Python, are not seen. SQL inside content strings (e.g. quiz text) can still be reported as tables.
136
+ - Structure is drawn for Python, JS/TS, SQL and Prisma. Other languages are tracked for changes but not drawn.
137
+ - JS/TS flowcharts are an outline (branches and calls in order), not a full parse.
138
+ - Steps close at turn ends only with hooks (Claude Code, opencode); elsewhere the agent calls `step` or a quiet period closes it.
139
+ - The VS Code extension was packaged and checked for syntax here, not exercised inside an editor.
140
+
141
+ ## Project layout
142
+
143
+ ```
144
+ src/mapwright/ analysis, tracking, MCP server, hooks, daemon, CLI, UI
145
+ integrations/ VS Code extension (.vsix included), Claude Code plugin, opencode plugin, Agent Skill
146
+ web/ website (landing, docs, setup) + scripts/build_site.py builds the live demo
147
+ docs/ SETUP (install, connect, deploy), COMMANDS, AGENT_PROTOCOL, ARCHITECTURE
148
+ scripts/ demo_session.py (scripted agent), build_site.py
149
+ tests/
150
+ ```
151
+
152
+ MIT licensed. The diagram renderer is [Mermaid](https://mermaid.js.org) 10.9.3 (MIT), bundled.
@@ -0,0 +1,48 @@
1
+ # Agent protocol
2
+
3
+ What an agent does with Mapwright, and why each part is shaped the way it is.
4
+
5
+ ## The loop
6
+
7
+ 1. **Start of a task:** call `map`. Read structure from it instead of listing directories and opening files.
8
+ 2. **Plan:** `todo add` for each part.
9
+ 3. **Before changing a function:** `symbol NAME` to see its callers, callees and tables. Open the file only to edit.
10
+ 4. **After each meaningful change:** `step` with a short title of what was done.
11
+ 5. **When a part is finished:** `todo done ID` with the symbol or file you changed as `evidence`.
12
+ 6. **When you implement a mechanism** (cache, retry, queue, auth …): `claim CONCEPT SYMBOL`.
13
+ 7. Optional: `note` a module's role; `link` two symbols the code does not connect directly.
14
+
15
+ With hooks (Claude Code, opencode), turn ends close a step even if the agent forgets step 4.
16
+
17
+ ## Why it is cheap
18
+
19
+ - Tool definitions total under 3,000 characters (they are sent with every request).
20
+ - `map` is capped (default 2,400 characters, about 600 tokens) and shrinks long sections first.
21
+ - No result contains source code. Results point at `file:line`, so the agent reads only what it needs.
22
+ - The agent sends titles and ids, never diagrams, file lists or summaries. Diagrams, icons, layouts and
23
+ flowcharts are built from the code by Mapwright.
24
+
25
+ ## Why it cannot be gamed
26
+
27
+ | The agent says | Mapwright checks |
28
+ |---|---|
29
+ | a step title | The changed files are computed. Titles that mention tests, migrations, routes, tables, docs or infrastructure are checked against what actually changed. |
30
+ | a todo is done | The evidence must exist and must have changed after the todo was added. |
31
+ | a symbol implements a concept | The concept's signals must appear in that symbol's code (decorators included). Only a module-level import counts as "weak". |
32
+ | a note or link | The symbols must exist; when they disappear the note or link is marked stale. |
33
+
34
+ ## MCP details
35
+
36
+ - Transport: stdio, JSON-RPC 2.0, one message per line. Protocol versions `2025-06-18`, `2025-03-26`, `2024-11-05`.
37
+ - Project root: `--root`, else `MAPWRIGHT_ROOT`, else the server's working directory (the nearest folder with `.git`).
38
+ - Errors in a tool are returned as `isError: true` with a one-line message; the session is never interrupted.
39
+
40
+ ## Hook events
41
+
42
+ `mapwright hook AGENT` reads one JSON object on stdin and always exits 0 without output.
43
+
44
+ | `hook_event_name` | Recorded |
45
+ |---|---|
46
+ | `UserPromptSubmit` (`prompt`) | the prompt, redacted, up to 300 characters |
47
+ | `PostToolUse` (`tool_name`, `tool_input`) | the tool and the files it named |
48
+ | `Stop` / `SessionEnd` | a turn end; closes a step if files changed and `auto_step` allows |
@@ -0,0 +1,50 @@
1
+ # Architecture
2
+
3
+ ```
4
+ agent ──stdio──▶ mcp.py ─┐ ┌─▶ render.py ─▶ Mermaid + node map ─▶ ui/app.js
5
+ agent ──hooks──▶ hooks.py┼─▶ track.Project ────────┤
6
+ CLI ─────────▶ cli.py ─┘ (refresh, steps, ├─▶ brief.py ─▶ compact text for agents
7
+ UI ──HTTP───▶ server.py annotations, verify) └─▶ flow.py ─▶ function flowcharts
8
+ │
9
+ ├─ analyze.py per-file analysis (cached by content hash) + link()
10
+ ├─ concepts.py catalog + detectors + claim evidence
11
+ └─ infra.py Docker, compose, Terraform, k8s, CI, env, SDKs
12
+ ```
13
+
14
+ ## Storage (`track.py`)
15
+
16
+ `~/.mapwright/projects/<name>-<hash>/`:
17
+
18
+ | File | Contents |
19
+ |---|---|
20
+ | `journal.jsonl` | Append-only events: `prompt`, `tool`, `turn_end`, `step`, `todo`, `todo_done`, `todo_drop`, `claim`, `note`, `link`, `retract` |
21
+ | `steps/NNNN.json.gz` | Per step: file index (path → content hash), the full model, changes with line counts, design delta, title check |
22
+ | `blobs/ab/<sha>.gz` | Every version of every tracked text file, stored once by hash; secret-looking files are never stored |
23
+ | `cache.json.gz` | Per-file analysis keyed by (mtime, size); a new process starts warm |
24
+
25
+ Several processes share a project (daemon, MCP server, hooks, CLI). Writes take an `flock` on the project
26
+ directory, re-entrant within a process. Annotations are derived by replaying the journal; verification is
27
+ recomputed against the current model each time it is read.
28
+
29
+ ## Analysis (`analyze.py`)
30
+
31
+ - Python: `ast` for imports (relative imports and aliases resolved), classes, functions and methods (args,
32
+ decorators, calls, complexity, docstring, algorithm hints), routes (FastAPI, Flask, router prefixes),
33
+ SQLAlchemy and Django models, SQL inside string literals.
34
+ - JS/TS: patterns for imports, classes, interfaces, functions, arrow functions, methods, Express-style and
35
+ Next.js routes. SQL: `CREATE TABLE`. Prisma: models.
36
+ - `link()` resolves module dependencies, then the call graph (bare calls within the module and its imports;
37
+ `self.x` within the class; `alias.f` through import aliases; `obj.m` only when a single method in reach
38
+ matches), then which functions touch which tables (ORM classes referenced, SQL table names in the function).
39
+ - Layers come from path conventions, then from content (routes → interface, tables → data).
40
+
41
+ ## Daemon (`server.py`)
42
+
43
+ ThreadingHTTPServer on 127.0.0.1. Token (Bearer) on every `/v1` route, Host allowlist, no cross-origin
44
+ requests, JSON-only POST. A watcher thread refreshes tracked projects and closes automatic steps.
45
+
46
+ ## UI (`ui/`)
47
+
48
+ No framework and no build step. `app.js` renders the IDE frame, polls `/v1/p/<key>/version`, and renders
49
+ diagrams with the bundled Mermaid in strict mode with HTML labels off. Clickable nodes come from the node
50
+ map each renderer returns. The website's demo uses the same UI with a recorded bundle of API responses.
@@ -0,0 +1,85 @@
1
+ # Commands
2
+
3
+ `mw` is a short alias for `mapwright`. Every command has `--help`. Commands that act on a project use the
4
+ current folder (or `--path DIR`).
5
+
6
+ ## Start and stop
7
+
8
+ | Command | What it does |
9
+ |---|---|
10
+ | `mapwright init [--connect AGENT] [--agents-md [FILE]] [--local \| --home DIR] [--apply-ignore]` | Track this project; the current state becomes step 0. Warns when `max_files` truncates the scan and suggests ignores for bulky generated/data folders (`--apply-ignore` saves them) |
11
+ | `mapwright init --local` / `--home DIR` | Keep this project's history in `<project>/.mapwright` (or DIR, relative to the project root) instead of `~/.mapwright`. Creates it with mode 0700, writes the marker `.mapwright/home.json`, adds it to `.gitignore`. With `--connect X` the MCP entry gets `env.MAPWRIGHT_HOME` and Claude Code hooks are prefixed with `MAPWRIGHT_HOME=…` |
12
+ | `mapwright open [--print] [--json] [--web [--site URL]]` | Open the map in the browser (starts the daemon if needed). `--web` opens the hosted website instead; its page calls your local daemon directly (the token travels in the URL hash, never to the host), and the site is added to `web_origins` |
13
+ | `mapwright up [-d] [--no-watch]` · `mapwright down` | Start (foreground or background) or stop the daemon |
14
+ | `mapwright watch` | Track from the files alone, without the daemon or any agent integration |
15
+ | `mapwright doctor` | Check the setup |
16
+ | `mapwright guide` | Quick reference |
17
+
18
+ ## Agents
19
+
20
+ | Command | What it does |
21
+ |---|---|
22
+ | `mapwright connect --list` | Agents found on this machine and what is connected |
23
+ | `mapwright connect AGENT [--scope project\|user]` | Write the agent's MCP config (and hooks for Claude Code) |
24
+ | `mapwright connect --print AGENT` | Print the config to paste by hand |
25
+ | `mapwright disconnect AGENT [--scope …]` | Remove it again; config files (and empty `.claude/`, `.cursor/`, `.vscode/`, `.gemini/` folders) that are left with nothing in them are deleted |
26
+ | `mapwright agents-md [--file AGENTS.md\|CLAUDE.md\|GEMINI.md\|.cursorrules]` | Add six lines of usage notes for agents |
27
+ | `mapwright mcp [--root DIR]` | The MCP server on stdio (agents start this) |
28
+ | `mapwright hook AGENT` | Hook entry point (agents call this with JSON on stdin) |
29
+
30
+ Agents: `claude-code`, `cursor`, `vscode`, `windsurf`, `opencode`, `codex`, `gemini`, `claude-desktop`;
31
+ print-only: `cline`, `zed`, `jetbrains`, `any`.
32
+
33
+ ## While the agent works
34
+
35
+ | Command | What it does |
36
+ |---|---|
37
+ | `mapwright status [--json]` | Current step, pending changes, todos, problems |
38
+ | `mapwright steps` | Every step with its changes and design delta |
39
+ | `mapwright changes [--step N] [--diff]` | File changes since the last step, or in step N |
40
+ | `mapwright step "TITLE" [--intent "WHY"]` | Close a step yourself |
41
+ | `mapwright problems` | Claims, notes, links, todos and step titles that do not check out |
42
+ | `mapwright todo add TEXT` · `todo done ID --evidence SYMBOL` · `todo drop ID` · `todo list` | The plan |
43
+
44
+ ## For agents (also available as MCP tools)
45
+
46
+ | Command | MCP tool | What it does |
47
+ |---|---|---|
48
+ | `mapwright brief [--budget N] [--focus PATH]` | `map` | The map as compact text |
49
+ | `mapwright find QUERY` | `find` | Locate symbols |
50
+ | `mapwright symbol NAME` | `symbol` | Callers, callees, tables, routes, history |
51
+ | `mapwright step "TITLE"` | `step` | Record a step |
52
+ | `mapwright todo …` | `todo` | Plan items, verified on done |
53
+ | `mapwright claim CONCEPT SYMBOL [--note …]` | `claim` | Tag a mechanism; checked against the code |
54
+ | `mapwright note SYMBOL ROLE…` | `note` | One-line role, shown on the map |
55
+ | `mapwright link FROM TO [--label …]` | `link` | A relation the code cannot show |
56
+ | `mapwright catalog` | `catalog` | Concept ids |
57
+
58
+ ## Diagrams and export
59
+
60
+ | Command | What it does |
61
+ |---|---|
62
+ | `mapwright diagram architecture\|files\|classes\|data\|cloud\|processes\|calls\|concepts [--step N] [--focus X]` | Print a diagram as Mermaid |
63
+ | `mapwright flow FUNCTION` | Flowchart of one function |
64
+ | `mapwright export -o DIR` | `MAP.md` (renders on GitHub) + every diagram + steps and verification as JSON |
65
+
66
+ ## Settings
67
+
68
+ `mapwright settings` lists them; `mapwright settings KEY VALUE` changes one (also in the UI: Settings).
69
+
70
+ | Setting | Default | Meaning |
71
+ |---|---|---|
72
+ | `auto_step` | `turn` | `turn`: close a step when an agent turn ends (Claude Code Stop/SessionEnd hooks). Waits while another session in the project is mid-turn (up to 5 min), ignores subagent stops and re-fired Stop hooks, merges turn ends within 2 s, and creates no step for turns with no file changes or only generated/lockfile changes (lockfiles, build output, minified/map files, shards, large data JSON, tool config, ignored files); those are still recorded, collapsed into one `generated/lockfile (N files)` line, and not counted. Titles come from the first clear sentence of the prompt (≤ ~60 chars) or are computed from the changes for long prompts; the prompt is kept (redacted) as the intent · `idle`: after a quiet period · `off` |
73
+ | `idle_seconds` | `60` | Quiet period for `idle` (and for agents without hooks) |
74
+ | `watch_interval` | `2.0` | Seconds between scans while the daemon runs |
75
+ | `brief_budget` | `2400` | Characters in `map` / `brief` (about 600 tokens) |
76
+ | `max_files` | `5000` | Cap on tracked files. When hit, `init`, `doctor` and `state` (`truncated_info`) show files seen and the folders that used the budget |
77
+ | `web_origins` | `["https://mapwright.pages.dev"]` | Hosted sites allowed to call this daemon from the browser. Exact origins only (https, or loopback http); the token is still required |
78
+ | `respect_gitignore` | `true` | Skip files matched by `.gitignore` (root and nested) and `.git/info/exclude` |
79
+ | `ignore` | `[]` | Extra names or gitignore-style patterns, e.g. `["public/question-bank/**", "*.pdf", "apps/*/dist"]`. Plain names match at any depth; `!pattern` re-includes something `.gitignore` excludes |
80
+ | `redact` | `true` | Redact secrets in code shown in the UI |
81
+ | `theme` · `font_size` | `dark` · `13` | Appearance |
82
+
83
+ Home resolution: `MAPWRIGHT_HOME` env, then a project-local home found by walking up from the current directory (or `--path`, `--root`, or the hook's cwd) to a `.mapwright/home.json` marker, then `~/.mapwright`. One daemon serves one home, so `open`/`up` start it with the project's home and refuse (with a message) if a daemon with a different home holds the port.
84
+
85
+ Environment: `MAPWRIGHT_HOME` (default `~/.mapwright`), `MAPWRIGHT_PORT` (default `7979`), `MAPWRIGHT_ROOT` (project for `mcp`).
@@ -0,0 +1,41 @@
1
+ # Releasing to PyPI
2
+
3
+ The PyPI name `mapwright` belongs to an unrelated project, so Mapwright is published as **`mapwright-agent`**.
4
+ The command is still `mapwright` and the Python package is still `mapwright`:
5
+
6
+ ```bash
7
+ pipx install mapwright-agent
8
+ mapwright --version
9
+ ```
10
+
11
+ Do not install it into the same environment as the other `mapwright` package (pipx keeps them apart).
12
+
13
+ ## One-time setup (no API token needed: PyPI trusted publishing)
14
+
15
+ 1. Create accounts at pypi.org (and test.pypi.org to rehearse) and turn on 2FA.
16
+ 2. On PyPI go to *Your account → Publishing → Add a new pending publisher* and enter:
17
+ project `mapwright-agent`, owner `1mystic`, repository `Mapwright`, workflow `release.yml`, environment `pypi`.
18
+ (Same on test.pypi.org with environment `testpypi`.)
19
+ 3. On GitHub: *Settings → Environments*: create `pypi` (add yourself as required reviewer if you want a manual approval before each release) and `testpypi`.
20
+
21
+ ## Each release
22
+
23
+ 1. Bump `__version__` in `src/mapwright/__init__.py` (the only place; `pyproject.toml` reads it), move the
24
+ `CHANGELOG.md` "Unreleased" notes under the new version, commit, push.
25
+ 2. Rehearse (optional): *Actions → release → Run workflow → testpypi*, then
26
+ `pipx install --index-url https://test.pypi.org/simple/ mapwright-agent`.
27
+ 3. Publish: `git tag vX.Y.Z && git push origin vX.Y.Z`. The workflow checks the tag matches the version, runs the
28
+ tests, builds, creates a GitHub release with the wheel and sdist attached, and publishes to PyPI once the
29
+ repository variable `PUBLISH_PYPI` is `true` (*Settings → Secrets and variables → Actions → Variables*; set it after the trusted publisher exists).
30
+
31
+ ## Install without PyPI
32
+
33
+ ```bash
34
+ pipx install git+https://github.com/1mystic/Mapwright.git # latest main
35
+ pipx install git+https://github.com/1mystic/Mapwright.git@v0.2.0 # a release
36
+ pipx install https://github.com/1mystic/Mapwright/releases/download/v0.2.0/mapwright_agent-0.2.0-py3-none-any.whl
37
+ ```
38
+
39
+ ## Actions run only when you start them
40
+
41
+ `tests` and `website` are manual (*Actions → workflow → Run workflow*); `release` runs only on a `v*` tag or by hand. Nothing runs on ordinary pushes, so there are no failure emails.