mapwright-agent 0.2.0__py3-none-any.whl

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.
@@ -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,34 @@
1
+ mapwright/__init__.py,sha256=lNdcYS2MBwN7te097sch469MfCMtXFi-2A3uNy9std4,90
2
+ mapwright/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
3
+ mapwright/analyze.py,sha256=j4lL7NljRD6NpQ1z2xMe9NejTqE2vHY6hqFT5ZX2xLw,42203
4
+ mapwright/brief.py,sha256=CQWvLQc7641kVrlFR1CQodD2M4f9SjRMuGo6K5zpqk8,10563
5
+ mapwright/cli.py,sha256=U7gLlP_2rfOsZqa_heKFaFE1ob2PznOJk42ucupI7_0,26916
6
+ mapwright/concepts.py,sha256=C3pXl53AbdMXzE3BxbpRCuo6bZQnMZ6mMETsFvq9tG0,15041
7
+ mapwright/config.py,sha256=pR8zntaRZZN4JVEsb_RUQB7pOI6kN5FXXZrGWoVF9Us,6943
8
+ mapwright/connect.py,sha256=861aH5lksvtdaw5NCbAQ3jGY5bkET5SoNDvS8fIqFbc,15781
9
+ mapwright/export.py,sha256=duLAFIYZrqbYkPCFM0xUQ9GJVyW_4k7ActyWbNQIDaU,2366
10
+ mapwright/firestore.py,sha256=6JZfd_ycWwzvJg8O3dlbqEDnDi-7MSh0hSBcTsPvOQg,7540
11
+ mapwright/flow.py,sha256=LYFUsj8E4zze6YUHTh2HfHRyXhBXfkQLcK0bIeuZJL0,10571
12
+ mapwright/hooks.py,sha256=IixSRL5EAiuTXUCu_L1gQf0aiHvh4eYvbh5aGGp-53I,5263
13
+ mapwright/ignore.py,sha256=V7RiXCjTDKtuIOXs1AVWwqrXY1c1ufSnt1RuMFoyfbY,10014
14
+ mapwright/infra.py,sha256=Ng1bvzjasXj7DISGxB9Yq9U6OL4CvK-iXXNbS9zKPGk,16882
15
+ mapwright/mcp.py,sha256=CCDzjvJPfvZcdCwXjGjDpyJt5iT8N3eyM-8FdvyrMqg,8050
16
+ mapwright/noise.py,sha256=XuP_nLI50aYz3ujI_vAHWbP1aIPGaB4TTiwwnzaAOHk,3490
17
+ mapwright/redact.py,sha256=UKSdvlf0_LdLfmxz7rt1EMkgDRyzVEFP9XziEvbtHYk,2180
18
+ mapwright/render.py,sha256=vlUPmYRT9A7BzXZOGRHJcx7Jn7zqvQI8poxZ0pdFz_o,21897
19
+ mapwright/routes_js.py,sha256=5S6zeGY98MBGgVN43zAv5ExIejQYtbpNVeH3yNx5E6Y,11510
20
+ mapwright/server.py,sha256=ph5dO4vd7-TqG71Xa9xYJ5ZqbaXvhD8Z7QdZ_BCnsOg,21427
21
+ mapwright/titles.py,sha256=CvV8v1TJsQwkc-sFxX8VeLgJLzkMtaDmvreHBxy8X2Y,4658
22
+ mapwright/track.py,sha256=2kBDqcfpjwqMIBiUThLw33b33V1HID016bKXQSRd5TE,36954
23
+ mapwright/ui/app.css,sha256=3rmVc6fk4kUym2W6ra8qQco6293VP72xQC4XbrfAHJc,35159
24
+ mapwright/ui/app.js,sha256=UTDm3ZfqUT1pIuhaXgnPI817BQ40tqb0PVoHeNpvH7g,104645
25
+ mapwright/ui/icons.svg,sha256=NZcZgD51EY6CtLTrLTOaXBLMU6vfwcQEnfXW_oMsGN4,16286
26
+ mapwright/ui/index.html,sha256=YKQK5ChcrRCoKfkASDGGzA_HlQihFUPndq_1btZ88as,2762
27
+ mapwright/ui/mark.svg,sha256=8aHjqVb-MwxDDVbVfh1up0RcVzZou0d_Pxlu1ABxsjQ,351
28
+ mapwright/ui/vendor/mermaid.LICENSE,sha256=7J-2fcsl7MxBbtVuGquBkiLIBaKkv-TLGedVa_L_3oA,1089
29
+ mapwright/ui/vendor/mermaid.min.js,sha256=Wo7JGCC9Va_vBJBoSJNpkQ5dbOcMgQOVLyfinT526Lw,3336760
30
+ mapwright_agent-0.2.0.dist-info/METADATA,sha256=_8Lniu_eLsRQXBozpO8JhhOE5Dg67uSmNEhu5i4uTpg,12279
31
+ mapwright_agent-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
32
+ mapwright_agent-0.2.0.dist-info/entry_points.txt,sha256=LQueB8xwV3Vi6JWnAvk7TkNfZMOgz5aOGerOBg1wiFE,73
33
+ mapwright_agent-0.2.0.dist-info/licenses/LICENSE,sha256=F-FIef-P3B1siJUBBGKYJ575_tPpBgUNu1W16g4VYQI,1081
34
+ mapwright_agent-0.2.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ mapwright = mapwright.cli:main
3
+ mw = mapwright.cli:main
@@ -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.