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.
- mapwright_agent-0.2.0/.gitignore +9 -0
- mapwright_agent-0.2.0/CHANGELOG.md +30 -0
- mapwright_agent-0.2.0/LICENSE +21 -0
- mapwright_agent-0.2.0/PKG-INFO +179 -0
- mapwright_agent-0.2.0/README.md +152 -0
- mapwright_agent-0.2.0/docs/AGENT_PROTOCOL.md +48 -0
- mapwright_agent-0.2.0/docs/ARCHITECTURE.md +50 -0
- mapwright_agent-0.2.0/docs/COMMANDS.md +85 -0
- mapwright_agent-0.2.0/docs/RELEASING.md +41 -0
- mapwright_agent-0.2.0/docs/ROADMAP.md +49 -0
- mapwright_agent-0.2.0/docs/SETUP.md +273 -0
- mapwright_agent-0.2.0/docs/img/architecture.png +0 -0
- mapwright_agent-0.2.0/docs/img/cloud.png +0 -0
- mapwright_agent-0.2.0/docs/img/concepts.png +0 -0
- mapwright_agent-0.2.0/docs/img/data.png +0 -0
- mapwright_agent-0.2.0/docs/img/light.png +0 -0
- mapwright_agent-0.2.0/docs/img/logic.png +0 -0
- mapwright_agent-0.2.0/docs/img/overview.png +0 -0
- mapwright_agent-0.2.0/docs/img/processes.png +0 -0
- mapwright_agent-0.2.0/docs/img/settings.png +0 -0
- mapwright_agent-0.2.0/docs/img/setup.png +0 -0
- mapwright_agent-0.2.0/docs/img/timeline.png +0 -0
- mapwright_agent-0.2.0/integrations/claude-code/.claude-plugin/plugin.json +8 -0
- mapwright_agent-0.2.0/integrations/claude-code/.mcp.json +5 -0
- mapwright_agent-0.2.0/integrations/claude-code/hooks/hooks.json +7 -0
- mapwright_agent-0.2.0/integrations/claude-code/skills/mapwright/SKILL.md +45 -0
- mapwright_agent-0.2.0/integrations/opencode/mapwright.js +30 -0
- mapwright_agent-0.2.0/integrations/skills/mapwright/SKILL.md +45 -0
- mapwright_agent-0.2.0/integrations/vscode/LICENSE +21 -0
- mapwright_agent-0.2.0/integrations/vscode/README.md +22 -0
- mapwright_agent-0.2.0/integrations/vscode/extension.js +91 -0
- mapwright_agent-0.2.0/integrations/vscode/icon.png +0 -0
- mapwright_agent-0.2.0/integrations/vscode/mapwright-vscode-0.1.0.vsix +0 -0
- mapwright_agent-0.2.0/integrations/vscode/package.json +103 -0
- mapwright_agent-0.2.0/pyproject.toml +50 -0
- mapwright_agent-0.2.0/scripts/build_site.py +117 -0
- mapwright_agent-0.2.0/scripts/demo_session.py +444 -0
- mapwright_agent-0.2.0/src/mapwright/__init__.py +3 -0
- mapwright_agent-0.2.0/src/mapwright/__main__.py +3 -0
- mapwright_agent-0.2.0/src/mapwright/analyze.py +809 -0
- mapwright_agent-0.2.0/src/mapwright/brief.py +208 -0
- mapwright_agent-0.2.0/src/mapwright/cli.py +596 -0
- mapwright_agent-0.2.0/src/mapwright/concepts.py +190 -0
- mapwright_agent-0.2.0/src/mapwright/config.py +204 -0
- mapwright_agent-0.2.0/src/mapwright/connect.py +337 -0
- mapwright_agent-0.2.0/src/mapwright/export.py +42 -0
- mapwright_agent-0.2.0/src/mapwright/firestore.py +168 -0
- mapwright_agent-0.2.0/src/mapwright/flow.py +238 -0
- mapwright_agent-0.2.0/src/mapwright/hooks.py +111 -0
- mapwright_agent-0.2.0/src/mapwright/ignore.py +248 -0
- mapwright_agent-0.2.0/src/mapwright/infra.py +253 -0
- mapwright_agent-0.2.0/src/mapwright/mcp.py +153 -0
- mapwright_agent-0.2.0/src/mapwright/noise.py +80 -0
- mapwright_agent-0.2.0/src/mapwright/redact.py +39 -0
- mapwright_agent-0.2.0/src/mapwright/render.py +428 -0
- mapwright_agent-0.2.0/src/mapwright/routes_js.py +282 -0
- mapwright_agent-0.2.0/src/mapwright/server.py +388 -0
- mapwright_agent-0.2.0/src/mapwright/titles.py +111 -0
- mapwright_agent-0.2.0/src/mapwright/track.py +715 -0
- mapwright_agent-0.2.0/src/mapwright/ui/app.css +277 -0
- mapwright_agent-0.2.0/src/mapwright/ui/app.js +1025 -0
- mapwright_agent-0.2.0/src/mapwright/ui/icons.svg +73 -0
- mapwright_agent-0.2.0/src/mapwright/ui/index.html +35 -0
- mapwright_agent-0.2.0/src/mapwright/ui/mark.svg +1 -0
- mapwright_agent-0.2.0/src/mapwright/ui/vendor/mermaid.LICENSE +21 -0
- mapwright_agent-0.2.0/src/mapwright/ui/vendor/mermaid.min.js +2029 -0
- mapwright_agent-0.2.0/tests/conftest.py +20 -0
- mapwright_agent-0.2.0/tests/test_analysis.py +128 -0
- mapwright_agent-0.2.0/tests/test_autostep.py +125 -0
- mapwright_agent-0.2.0/tests/test_disconnect.py +104 -0
- mapwright_agent-0.2.0/tests/test_firestore.py +75 -0
- mapwright_agent-0.2.0/tests/test_ignore.py +157 -0
- mapwright_agent-0.2.0/tests/test_local_home.py +150 -0
- mapwright_agent-0.2.0/tests/test_release.py +18 -0
- mapwright_agent-0.2.0/tests/test_routes_js.py +69 -0
- mapwright_agent-0.2.0/tests/test_system_view.py +20 -0
- mapwright_agent-0.2.0/tests/test_titles.py +43 -0
- mapwright_agent-0.2.0/tests/test_tracking.py +227 -0
- mapwright_agent-0.2.0/tests/test_ui_auth.py +56 -0
- mapwright_agent-0.2.0/tests/test_web_origin.py +62 -0
|
@@ -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 & 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 & 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.
|