Skip to content
Back to search

mellos-mapping

Marketplace for the Mellos Mapping plugin

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/guangminju--mellos-mapping/badge.svg)](/listings/guangminju--mellos-mapping)

HTML

<a href="/listings/guangminju--mellos-mapping"><img src="/api/listings/guangminju--mellos-mapping/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Clone the branch for your host, then run one command. No build is required.

| Branch | Audience | Command from the clone | | --- | --- | --- | | `main` | Shared source / either host | `node install.mjs chatgpt-app` or `node install.mjs claude` | | `claude` | Claude Code | `node install.mjs` | | `chatgpt-app` | ChatGPT desktop, Codex mode | `node install.mjs` |

Requires Node.js 18.17+ on the 18.x line, or 20.3+, and the corresponding host CLI on PATH. Supported platforms are Windows 10+, macOS 13.0+ and Linux with glibc 2.28+, each on x64 or arm64. The OS must also meet the selected Node.js version's requirements. Native lock bindings ship with the release; no local compilation is needed. The installer checks release integrity and all eight MCP tools, retains the runtime outside the clone, and configures the host. Start a new conversation after installation. See [release and branch instructions](docs/releasing.md).

Claude Code's marketplace installation is also available:

Two lines inside any Claude Code conversation:

/plugin marketplace add GuangminJu/mellos-mapping
/plugin install mellos-mapping@mellos-mapping

Or one line in a terminal:

claude plugin marketplace add GuangminJu/mellos-mapping && claude plugin install mellos-mapping@mellos-mapping

Requires the same [Node.js and platform versions](#install) on PATH (install Node separately when using native Claude Code). No build step: `dist/` is committed, so a clone runs as-is — `dist/server.mjs` (the MCP server), `dist/watch.mjs` (the pane), `dist/mmap.mjs` (the `mmap` toggle), `dist/hook-session-start.mjs` (the `SessionStart` hook that `hooks/hooks.json` registers) and `dist/store-paths.mjs` (the store's path vocabulary, which the plain-node pane launcher imports instead of restating filenames).

**omp (Oh My Pi)** reads the same plugin layout the Claude Code edition ships — the same marketplace catalog, `.mcp.json`, skill and slash command — so one release serves both hosts:

omp plugin marketplace add GuangminJu/mellos-mapping
omp plugin install mellos-mapping@mellos-mapping

That install follows `main`, where a release is a version bump. To freeze a version instead, add a checkout of one — the Claude Code edition ZIP from the GitHub Release, or a clone at the release tag:

omp plugin marketplace add "<checkout or extracted release directory>"
omp plugin install mellos-mapping@mellos-mapping

omp never reads `hooks/hooks.json`, so the session paragraph arrives through the plugin's omp host adapter (`dist/omp-extension.mjs`, declared in `package.json#omp.extensions`): the same store, the same policy text, and the same `mmap` shim install as the Claude hook. The pane is the same terminal split beside the session. Install it *as a plugin*: neither `omp plugin link` nor the npm package is a plugin, and both would leave the tools behind. See [omp installation and limitations](docs/distributions/omp.md).

**pi** reads none of that layout: it loads an extension and has no MCP of its own, by design. So the plugin speaks MCP to itself — the extension declared in `package.json#pi.extensions` (`dist/pi-extension.mjs`) starts the same `dist/server.mjs` in the session's directory, which makes the eight `mmap_*` tools the same eight, under the same names, and builds the session paragraph from the same store and the same policy text the Claude hook prints:

pi install npm:mellos-mapping

Add `-l` to install it for the current project instead of every one, then start a new session: pi discovers packages at session start. The package's `skills/` and `commands/` travel with it — the same map discipline, and `/mmap` for the same slash command. See [pi installation and behaviour](docs/distributions/pi.md).

The first session after installing asks you **one** question — how eager mapping should be — and records the answer for every project you will ever open. From then on the hook carries it into each new session by itself; there

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "mellos-mapping",
  3. "owner": {
  4. "name": "Mellos"
  5. },
  6. "description": "Marketplace for the Mellos Mapping plugin",
  7. "plugins": [
  8. {
  9. "name": "mellos-mapping",
  10. "source": "./",
  11. "description": "A live layered dependency map for bottom-up development: ghost the design first, then light nodes up from the bottom as they are built and verified",
  12. "version": "0.28.0",
  13. "author": { "name": "Mellos" },
  14. "tags": ["visualization", "bottom-up", "architecture", "dependency-map", "progress"]
  15. }
  16. ]
  17. }
README.md · README · 797 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Mellos Mapping
  2. [![npm](https://img.shields.io/npm/v/mellos-mapping?logo=npm&logoColor=white&label=npm&color=cb3837)](https://www.npmjs.com/package/mellos-mapping)
  3. [![downloads](https://img.shields.io/npm/dm/mellos-mapping?label=downloads&color=cb3837)](https://www.npmjs.com/package/mellos-mapping)
  4. [![MCP registry](https://img.shields.io/badge/MCP_registry-listed-2f6feb)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.GuangminJu/mellos-mapping)
  5. [![CI](https://img.shields.io/github/actions/workflow/status/GuangminJu/mellos-mapping/ci.yml?branch=main&label=CI)](https://github.com/GuangminJu/mellos-mapping/actions/workflows/ci.yml)
  6. [![license](https://img.shields.io/badge/license-MIT-444)](LICENSE)
  7. [![LINUX DO](https://img.shields.io/badge/LINUX%20DO-community-ffb400?logo=discourse&logoColor=white)](https://linux.do)
  8. English | [简体中文](README.zh-CN.md)
  9. A live, terminal-native map of bottom-up development for
  10. [Claude Code](https://claude.com/claude-code), ChatGPT desktop Codex mode and Codex CLI.
  11. <p align="center">
  12. <picture>
  13. <source media="(prefers-color-scheme: light)" srcset="docs/demo-light.svg">
  14. <img alt="One declare puts the whole ghost design on screen, then the nodes light up from the bottom — a foundation cracks, the damage spreads upward, and green is earned back" src="docs/demo.svg" width="620">
  15. </picture>
  16. </p>
  17. While Claude builds your system, a split pane beside the conversation shows
  18. the system's **layered dependency map**: primitive layers at the bottom,
  19. dependency edges that may only point downward, ghost nodes for what is
  20. designed, a spinner on what is being built right now, and solid green for
  21. what is built *and verified*.
  22. <p align="center">
  23. <img alt="A Claude Code session with the Mellos map pane beside it: a six-layer game engine design, L0 and L1 nodes solid green, the upper layers still dashed ghost nodes" src="docs/session-claude-code.png">
  24. </p>
  25. *A real session: Claude Code on the left, the map pane on the right. L0 is
  26. verified, L1 just lit up, everything above is still a ghost.*
  27. ## Why
  28. Most progress reporting is a task list — a top-down worldview. A Mellos map
  29. grows the other way: an upper node can only stand on nodes below it, and the
  30. picture makes the discipline visible:
  31. - **The ghost design appears before any code.** Claude declares the whole
  32. intended structure as dashed ghost nodes first; you can veto a bad design
  33. while it is still only a picture.
  34. - **The spinner is where Claude's attention is.** One glance answers "what is
  35. it doing right now, and on top of what?"
  36. - **Done means verified.** A node turns solid green only with evidence (a
  37. passing test run). If later work cracks a foundation, the node turns red —
  38. a cracked foundation under a spinning upper floor is the most honest status
  39. report there is.
  40. - **The map is a ledger, not a judge.** The tools refuse only structural
  41. corruption (an edge pointing upward, a duplicate rank). Workflow is
  42. Claude's discipline, defined in the bundled skill; violations are made
  43. *visible*, never silently blocked.
  44. ## Install
  45. Clone the branch for your host, then run one command. No build is required.
  46. | Branch | Audience | Command from the clone |
  47. | --- | --- | --- |
  48. | `main` | Shared source / either host | `node install.mjs chatgpt-app` or `node install.mjs claude` |
  49. | `claude` | Claude Code | `node install.mjs` |
  50. | `chatgpt-app` | ChatGPT desktop, Codex mode | `node install.mjs` |
  51. Requires Node.js 18.17+ on the 18.x line, or 20.3+, and the corresponding host CLI
  52. on PATH. Supported platforms are Windows 10+, macOS 13.0+ and Linux with glibc
  53. 2.28+, each on x64 or arm64. The OS must also meet the selected Node.js version's
  54. requirements. Native lock bindings ship with the release; no local compilation
  55. is needed. The installer checks
  56. release integrity and all eight MCP tools, retains the runtime outside the clone,
  57. and configures the host. Start a new conversation after installation.
  58. See [release and branch instructions](docs/releasing.md).
  59. Claude Code's marketplace installation is also available:
  60. Two lines inside any Claude Code conversation:
  61. ```
  62. /plugin marketplace add GuangminJu/mellos-mapping
  63. /plugin install mellos-mapping@mellos-mapping
  64. ```
  65. Or one line in a terminal:
  66. ```
  67. claude plugin marketplace add GuangminJu/mellos-mapping && claude plugin install mellos-mapping@mellos-mapping
  68. ```
  69. Requires the same [Node.js and platform versions](#install) on PATH (install
  70. Node separately when using native Claude Code). No build step: `dist/` is
  71. committed, so a clone runs as-is —
  72. `dist/server.mjs` (the MCP server), `dist/watch.mjs` (the pane),
  73. `dist/mmap.mjs` (the `mmap` toggle), `dist/hook-session-start.mjs` (the
  74. `SessionStart` hook that `hooks/hooks.json` registers) and
  75. `dist/store-paths.mjs` (the store's path vocabulary, which the plain-node pane
  76. launcher imports instead of restating filenames).
  77. **omp (Oh My Pi)** reads the same plugin layout the Claude Code edition ships —
  78. the same marketplace catalog, `.mcp.json`, skill and slash command — so one
  79. release serves both hosts:
  80. ```
  81. omp plugin marketplace add GuangminJu/mellos-mapping
  82. omp plugin install mellos-mapping@mellos-mapping
  83. ```
  84. That install follows `main`, where a release is a version bump. To freeze a
  85. version instead, add a checkout of one — the Claude Code edition ZIP from the
  86. GitHub Release, or a clone at the release tag:
  87. ```
  88. omp plugin marketplace add "<checkout or extracted release directory>"
  89. omp plugin install mellos-mapping@mellos-mapping
  90. ```
  91. omp never reads `hooks/hooks.json`, so the session paragraph arrives through the
  92. plugin's omp host adapter (`dist/omp-extension.mjs`, declared in
  93. `package.json#omp.extensions`): the same store, the same policy text, and the
  94. same `mmap` shim install as the Claude hook. The pane is the same terminal
  95. split beside the session. Install it *as a plugin*: neither `omp plugin link`
  96. nor the npm package is a plugin, and both would leave the tools behind. See
  97. [omp installation and limitations](docs/distributions/omp.md).
  98. **pi** reads none of that layout: it loads an extension and has no MCP of its
  99. own, by design. So the plugin speaks MCP to itself — the extension declared in
  100. `package.json#pi.extensions` (`dist/pi-extension.mjs`) starts the same
  101. `dist/server.mjs` in the session's directory, which makes the eight `mmap_*`
  102. tools the same eight, under the same names, and builds the session paragraph
  103. from the same store and the same policy text the Claude hook prints:
  104. ```
  105. pi install npm:mellos-mapping
  106. ```
  107. Add `-l` to install it for the current project instead of every one, then start
  108. a new session: pi discovers packages at session start. The package's `skills/`
  109. and `commands/` travel with it — the same map discipline, and `/mmap` for the
  110. same slash command. See [pi installation and behaviour](docs/distributions/pi.md).
  111. The first session after installing asks you **one** question — how eager
  112. mapping should be — and records the answer for every project you will ever
  113. open. From then on the hook carries it into each new session by itself; there
  114. is no per-project setup step. See
  115. [Setup: choose when maps open](#setup-choose-when-maps-open).
  116. The `mmap` terminal command (the pane's open/close toggle) installs itself on
  117. Windows: the same hook notices on session start when the shim is missing or
  118. points at an older install, writes `mmap.cmd` (cmd, PowerShell) and `mmap`
  119. (git-bash) into `%LOCALAPPDATA%\mellos-mapping\bin`, appends that one
  120. directory to your **user** PATH, and tells you so through the assistant. The
  121. PATH change reaches only new processes — and a new tab of a running Windows
  122. Terminal inherits the old environment, so close the terminal app entirely and
  123. reopen it before the first `mmap`. The PATH edit keeps the
  124. installer's guarantees: nothing happens when the entry is already there, and
  125. a PATH that `setx` would damage (flattened `%VARIABLE%` references, truncation
  126. past its limit) is refused outright.
  127. A refused PATH is not a dead end: the same two shims are then written into
  128. `%LOCALAPPDATA%\Microsoft\WindowsApps` (or `~/.local/bin`) — a directory your
  129. PATH already names — so `mmap` is runnable in a new terminal with no PATH
  130. change at all. Machines with a long PATH are exactly where that happens, and
  131. where it matters most. The command takes the page to open as an argument
  132. (`mmap omp-host-support`), and closes the pane when it is already open.
  133. The step behind it is still a command of its own, for the cases the hook does
  134. not cover — `--uninstall`, or re-adding a PATH entry you removed while the
  135. shims stayed put:
  136. ```
  137. node "<plugin dir>/scripts/install-mmap-command.mjs" [--uninstall]
  138. ```
  139. (`--json` prints the install outcome as one JSON line instead of prose — the
  140. mode the hook itself calls it in.) `npm i -g mellos-mapping` provides the
  141. same `mmap` via `bin`, no shims involved.
  142. ## Update
  143. ```
  144. claude plugin marketplace update mellos-mapping && claude plugin update mellos-mapping@mellos-mapping
  145. ```
  146. Two steps because `plugin update` compares against the locally cached
  147. marketplace clone — the first command is what actually pulls this repo.
  148. Restart Claude Code to apply. Releases are version bumps on `main`.
  149. (In-app, `/plugin` opens the same management UI.)
  150. omp updates with its own two steps:
  151. ```
  152. omp plugin marketplace update mellos-mapping && omp plugin upgrade mellos-mapping@mellos-mapping
  153. ```
  154. Close the pane first (`q` in it): the watcher runs from the plugin copy, and on
  155. Windows an open file cannot be renamed away, so an upgrade attempted while a
  156. pane is open can fail with `EPERM` and leave the plugin cache empty — repaired
  157. by `omp plugin install mellos-mapping@mellos-mapping --force`. Then: the first
  158. command refreshes the catalog, the second reinstalls from it. omp also
  159. refreshes a catalog entry it has not updated for a day at startup, unless
  160. `marketplace.autoUpdate` is `off` — in the default `notify` mode that check
  161. writes its finding to the debug log only, so `marketplace update` is the step
  162. that makes an update visible. `upgrade` does not compare versions: it
  163. force-reinstalls whatever the catalog names, which is why a release is
  164. identified by its version bump rather than gated by it. Restart omp afterwards,
  165. and reopen a pane still showing the old bundle (`q` in it, then `mmap_open`
  166. again).
  167. pi updates the package it installed, with no marketplace in between:
  168. ```
  169. pi update npm:mellos-mapping
  170. ```
  171. That is the npm source; a git source is reconciled to the ref your settings name
  172. by pi's own update, and a versioned spec (`npm:mellos-mapping@0.27.0`) is pinned
  173. and skipped. Restart the session afterwards: a session owns the map server
  174. process it started, so one still running keeps the copy it began with until it
  175. ends.
  176. ### Upgrading from 0.19
  177. 0.20 moved the store out of `.claude/` — the map belongs to this tool, not to
  178. one client — into `.mellos/`. The server and the watcher each perform the move
  179. once at startup, and print exactly one line on stderr when they do
  180. (`mellos-mapping: moved the legacy .claude map store to .mellos/ — commit the
  181. move.`):
  182. | 0.19 and earlier | 0.20 and later |
  183. | --- | --- |
  184. | `.claude/mellos-mapping.json` | `.mellos/map.json` |
  185. | `.claude/mellos-mapping.pages/` | `.mellos/pages/` |
  186. | `.claude/mellos-mapping.config.json` | `.mellos/config.json` |
  187. Nothing is merged and nothing is overwritten: a project that already has a
  188. `.mellos/` store (map, pages or config) is left untouched, whatever the legacy
  189. directory still holds. If you keep your maps in git, commit the move —
  190. `git add -A .claude .mellos` records it as renames rather than as a pile of
  191. deletions plus untracked files.
  192. That one move is the only time either process touches `.claude/`. Afterwards
  193. the tools write nowhere but `.mellos/`, and never outside the project
  194. directory they resolved at startup.
  195. ## ChatGPT App · Codex mode
  196. This is Codex mode in the ChatGPT desktop app (also called Codex App).
  197. From the source branch run the following command; on `chatgpt-app`, omit the
  198. host argument. It configures the desktop skill, marketplace and eight MCP tools.
  199. ```
  200. node install.mjs chatgpt-app
  201. ```
  202. Start a new conversation. The desktop skill defaults to **web-terminal**:
  203. `mmap_open {surface: "web-terminal", page: "<slug>"}` starts a local service,
  204. then the AI opens its URL in the current conversation's right browser panel.
  205. The mmap terminal starts automatically, with its own font-size selector;
  206. no manual paste or Computer Use is needed. Graphical SVG, native terminal and
  207. Markdown remain available. With an older MCP schema, run
  208. `node "<plugin root>/dist/web.mjs" "<project>" --terminal --page <slug>`.
  209. A queued panel request does not prove that the user can see it.
  210. See [desktop installation and limitations](docs/codex.md).
  211. For Codex CLI inside Windows Terminal (not the desktop integrated terminal), run
  212. `node <plugin root>/scripts/open-pane.mjs <project dir>` — it splits the
  213. terminal window hosting the session, keeping keyboard focus on the conversation.
  214. If that window cannot be identified or focused, it reports failure without
  215. opening elsewhere. `--window` explicitly chooses a separate window. Add
  216. `--page <slug>` to open on a particular page — and with a pane already open,
  217. rerunning with `--page` retargets the pane belonging to this console. A map
  218. open in another session or a separate window does not count as this split. The pane
  219. auto-follows the page being written — the map the agent is operating on
  220. right now; press `f` to toggle that (a manual page switch also turns it
  221. off), or start with `--no-follow`. Elsewhere run
  222. `node <plugin root>/dist/watch.mjs` from the project directory in a second
  223. terminal (or any terminal split). Both take the same flags — see
  224. [Pane flags](#pane-flags).
  225. ### Desktop Markdown map
  226. When the user chooses the document surface, the skill uses
  227. `mmap_open {surface: "markdown", page: "<slug>"}` and opens the returned file
  228. beside the current conversation. The document embeds a colored SVG dependency
  229. map plus module details, evidence, and child-page links. It needs no web server,
  230. browser rendering process, Mermaid support, or additional runtime dependencies.
  231. Successful MCP map writes regenerate enabled previews in `.mellos/previews/`;
  232. JSON remains the source of truth. Image nodes are static. File visibility and
  233. automatic viewer refresh belong to the desktop host. See the
  234. [desktop map guide](docs/codex.md#desktop-right-side-map) for regeneration,
  235. cache behavior, and limitations.
  236. ### Optional interactive web viewer
  237. An additional interactive web viewer is available with
  238. `mmap_open {surface: "web", page: "<slug>"}` or
  239. `node "<plugin root>/dist/web.mjs" "<project directory>" --page <slug>`.
  240. Open its returned URL in the host's right browser panel. It provides live
  241. updates, pan/zoom, hover and pinned details, search, dependency highlighting,
  242. filters, group overview, submaps and themes. Stop it with
  243. `node "<plugin root>/dist/web.mjs" "<project directory>" --stop`.
  244. Markdown/SVG and terminal workflows remain available; all surfaces share the
  245. same map data. See [web viewer details](docs/codex.md#optional-interactive-web-viewer).
  246. ## Any MCP client
  247. The server ships on npm, so any MCP client (Cursor, Windsurf, Zed,
  248. Gemini CLI, …) can run it with a standard stdio entry:
  249. ```
  250. npx -y mellos-mapping
  251. ```
  252. The map file lands in the client session's working directory
  253. (`.mellos/map.json`). Open the live pane from the same project:
  254. ```
  255. npx -y -p mellos-mapping mellos-mapping-watch
  256. ```
  257. The server picks its project directory in this order: `MELLOS_MAPPING_CWD`
  258. (an explicit override, for clients that spawn servers from a fixed
  259. directory), then `CLAUDE_PROJECT_DIR` (what Claude Code sets for plugin MCP
  260. servers), then the server process's own working directory. Set
  261. `MELLOS_MAPPING_CWD` when your client would otherwise start the server
  262. somewhere other than the project you are working in.
  263. The skill/discipline layer is Claude Code + Codex specific; other clients
  264. get the eight `mmap_*` tools and the pane, and bring their own prompting.
  265. ## Use
  266. 1. Ask Claude to build something non-trivial. The bundled skill has Claude
  267. declare the ghost design and keep the map current as it works.
  268. 2. The pane opens itself. Every write tells Claude whether anybody is
  269. actually looking (see [Who is watching](#who-is-watching)), and Claude
  270. opens or retargets the pane with `mmap_open` when nobody is — you never
  271. have to remember to. Open or close it yourself with `mmap` in any
  272. terminal, or `/mellos-mapping:mmap` in the conversation (Windows
  273. Terminal split on Windows, tmux split inside tmux, a Pebrel split inside
  274. Pebrel, or a printed command to run in any second terminal). On Windows the pane opens in the terminal
  275. window hosting YOUR session, even with several windows open; pass
  276. `--window` to put the map in its own dedicated window instead. Prefer
  277. `--ascii` if your font lacks box-drawing glyphs.
  278. 3. Watch nodes light up from the bottom. Interrupt when the picture worries
  279. you — that is what it is for.
  280. On Linux and macOS, `mmap_open` and `mmap` automatically use tmux. The launcher
  281. targets the inherited `TMUX`/`TMUX_PANE`; if the tool process lost those variables,
  282. it discovers the single attached session on the default tmux server. The default
  283. is a right split that preserves input focus; `--window` creates a new tmux window.
  284. Repeated opens reuse the watcher bound to that source pane or session window.
  285. For multiple attached sessions or a custom tmux socket, set these variables in
  286. the environment of the MCP server (restart it after changing them):
  287. | Variable | Meaning |
  288. | --- | --- |
  289. | `MELLOS_MAPPING_TMUX_TARGET` | Explicit tmux session or pane, such as `work:2.1` or `%7` |
  290. | `MELLOS_MAPPING_TMUX_SOCKET` | Absolute socket path, for example `/tmp/my-tmux/socket` |
  291. Inside [Pebrel](https://github.com/Kuddev/pebrel), `mmap_open` and `mmap` split the pane that hosts
  292. the conversation through Pebrel's runtime CLI (`PEBREL_CLI`). The launcher
  293. confirms which window that pane is in from its process tree, returns input focus
  294. to the conversation and types the watcher into the new pane's shell (PowerShell,
  295. cmd or a POSIX shell), which exits with it so the pane closes with the map.
  296. `--window` opens a new Pebrel window. Inside tmux, tmux owns the split.
  297. Ambiguous sessions, detached sessions and missing tmux produce a concrete error
  298. and a fully quoted watcher command, including the project and requested page,
  299. to paste into any visible terminal. Map writes remain available; after an open
  300. failure the assistant retries only when the environment changes or you ask.
  301. The pane is mouse-aware (xterm SGR any-event tracking — the same protocol
  302. htop and tmux speak):
  303. | Input | Action |
  304. | --- | --- |
  305. | hover a node | spotlight its wires; preview its details below the map |
  306. | click a node | pin it — details stay resident after the mouse leaves |
  307. | click empty space / `Esc` | unpin; with nothing pinned, `Esc` climbs out of a dive |
  308. | wheel / `+` `-` | zoom, anchored on the focused node (see the ladder below) |
  309. | left-drag | grab and pan when the map outgrows the pane |
  310. | shift+wheel | scroll vertically |
  311. | wheel tilt (horizontal) | pan sideways |
  312. | `hjkl` / arrows | nudge the view |
  313. | `Tab` / `Shift+Tab` / `1-9` / click a tab | switch pages (parallel maps) |
  314. | wheel on the tab row / click `‹` `›` | browse an overflowing tab strip without switching pages |
  315. | `f` | toggle auto-follow (see [Pages](#pages)) |
  316. | `x`, or click the `×` on the active tab | ask to delete the page on screen; press again inside the window and its file is removed (see [Pages](#pages)) |
  317. | double-click a `⊞` node | dive into its sub-map (a child page) |
  318. | `Backspace` / `Esc` | climb back out of the last dive |
  319. | drag the `⋯` divider | resize the detail panel — pull it up to read long design notes in full |
  320. | `0` | reset pan and zoom |
  321. | `q` / `Ctrl+C` | quit the pane |
  322. Every other key is inert, on purpose: an escape sequence the pane does not
  323. know (F-keys, Home/End, PgUp/PgDn, Insert/Delete, modified arrows) is
  324. consumed whole and does nothing, rather than having its payload bytes read
  325. as hotkeys.
  326. Zooming scales the picture first and switches display mode only at the ends
  327. of the ladder, so every level still shows meaningful data:
  328. ```
  329. detail+ ← detail ← 100% ← 85% ← 70% ← 55% ← overview
  330. ```
  331. - **zoom in past 100%** — `detail` unfolds evidence and the first three lines
  332. of the design notes inside the boxes; `detail+` widens them into reading
  333. cards (up to twelve note rows);
  334. - **85–55%** — whitespace tightens and labels truncate proportionally, boxes
  335. stay boxes;
  336. - **below 55%** — labels would stop meaning anything, so the map AGGREGATES:
  337. each declared group (a labeled subsystem within a band) becomes one box
  338. named `foundation subsystem 1/2` with its status derived from the members, edges
  339. collapse onto the groups, ungrouped nodes stay themselves. Like a real
  340. map, zooming out shows province names — not anonymous dots. (A map with
  341. no groups falls back to a pure glyph constellation with per-band counts.)
  342. The footer always names the level.
  343. Below the map, between it and the hint line, sits a fixed-height detail
  344. panel: a separator you can drag, a status-colored header, the focused node's
  345. evidence, both wire directions (`uses → … · used by ← …`, each neighbour
  346. carrying its own status glyph) and its design notes, word-wrapped. With
  347. nothing focused it shows the map's dashboard instead. Fixed height — details
  348. never float over the map and the layout never jumps.
  349. ### Glyphs
  350. One status, one glyph, everywhere a map is drawn — the pane's boxes, its tab
  351. strip and detail panel, and any other client reading the same store:
  352. | Unicode | ASCII | Meaning |
  353. | --- | --- | --- |
  354. | `·` | `.` | planned — declared, not started |
  355. | `⠿` | `*` | in-progress, at rest — a box that can animate spins through the braille frames (`⠋⠙⠹…`) instead, or a four-bar cycle in ASCII |
  356. | `■` | `#` | done, with evidence |
  357. | `□` | `o` | done, with **no** evidence recorded — same claim, nothing behind it |
  358. | `✗` | `X` | regressed: was done, now broken |
  359. | `⊞` | `+` | badge: the node links a sub-map; double-click dives in |
  360. The legend under the picture names the four statuses; `□ done, no evidence`
  361. joins it only on a map that actually contains one — the four are the
  362. vocabulary, that one is a rule being broken here and now. Documentation
  363. diagram kinds replace the status legend with their node-kind glyphs.
  364. ### Pane flags
  365. Both the pane launcher (`scripts/open-pane.mjs <project dir>`) and the
  366. watcher (`dist/watch.mjs`) take the same watcher flags; the launcher forwards
  367. them verbatim and rejects anything it does not know rather than dropping it.
  368. | Flag | Effect |
  369. | --- | --- |
  370. | `--page <slug>` | open on this page; with this console’s pane already running, retarget it instead of opening another |
  371. | `--ascii` | pure-ASCII repertoire, for fonts without box-drawing glyphs |
  372. | `--no-color` | no ANSI color |
  373. | `--no-mouse` | no mouse reporting, if your terminal multiplexer wants the mouse for itself |
  374. | `--no-follow` | start with auto-follow off |
  375. | `--interval <ms>` | poll interval; default 250, floored at 50 |
  376. Launcher-only: `--window` opens the dedicated "mellos-mapping" window instead
  377. of splitting the session's window, and `--force` opens another pane even
  378. though one is already running for this project. Watcher-only: `--file <path>`
  379. names the default page's state file (the launcher derives it from the project
  380. directory).
  381. Pane ownership is carried by the internal watcher flag `--owner <token>` and
  382. the optional `owner` field in viewer reports. Launchers derive the token from
  383. the source console process and its creation time; manual watchers can omit it.
  384. Focus and quit requests to a bound viewer use its PID, so another window of
  385. the same project cannot consume them. Bare `mmap` toggles only the pane bound
  386. to the current console; `mmap --window` toggles the separate project window.
  387. ### The mmap command
  388. `mmap`, typed in any terminal, is a **toggle**: it opens the map pane for the
  389. project you are standing in, or closes the one that is already open.
  390. | You type | What it does |
  391. | --- | --- |
  392. | `mmap` | nothing watching this project → open the pane; something watching → close it |
  393. | `mmap <page-slug>` | open on that page, or retarget an already-open pane to it — never closes |
  394. | `mmap --window` | open in the dedicated "mellos-mapping" window instead of splitting this one |
  395. | `mmap --force` | open another pane even though one is already running |
  396. The project is found the way git finds its root: from the current directory
  397. upwards, to the nearest one holding a `.mellos/` store. Standing in a project
  398. that has no map yet is fine — the pane opens on its standby screen and says so
  399. until the first `mmap_declare`.
  400. Closing goes through the store rather than through a signal: `mmap` writes a
  401. one-shot request beside the map, the pane consumes it on its next poll (250 ms
  402. by default) and exits, handing the terminal back exactly as it found it — mouse
  403. reporting off, cursor visible. A pane still on the standby screen closes the
  404. same way. The request is deleted as it is read, and a leftover from a pane that
  405. died is swept when the next one starts, so a stale request can never close a
  406. fresh pane.
  407. Every watcher flag above works here too, forwarded verbatim; an unknown one is
  408. a usage error, never dropped in silence. `mmap` needs
  409. [installing once](#install) unless you have the npm package. Inside a Claude
  410. Code conversation, `/mellos-mapping:mmap` opens the same pane.
  411. ### Pages
  412. A project can keep several maps side by side — **one effort = one page**.
  413. Claude targets a page by passing `page` to any `mmap_*` tool; the pane grows
  414. a tab bar as soon as a second page exists. The active tab is bold in its
  415. map's aggregate status color. Each page remembers its own pan, zoom and
  416. pinned node.
  417. By default the pane **follows the page being written** — the map the agent is
  418. operating on right now — so declares and updates bring the audience along by
  419. themselves. `f` toggles that, a manual page switch turns it off, and
  420. `--no-follow` starts it off; with follow off, a background page's change
  421. lights its tab in status color instead of stealing your view. An explicit
  422. `--page` outranks follow, and a page requested before it exists is shown the
  423. moment it appears.
  424. **Deleting a page.** An effort ends; its page does not have to stay. In the
  425. pane, `x` — or the `×` the active tab carries when the mouse is on — *asks*:
  426. the footer says `press x again to delete <page>`, and a second press within
  427. three seconds removes that page's file. Switching page, `Esc` or simply
  428. waiting takes the request back. The `×` sits on the active tab only, so
  429. clicking an inactive one switches to it first and offers its `×` on the next
  430. frame. From a tool call it is `mmap_remove {pages: ["slug", …]}`, applied
  431. after that call's map edits. Either way the file is gone for good — the maps
  432. are plain JSON, so committing them is the only undo there is.
  433. State lives in the tool-owned `.mellos/` directory at the project root:
  434. | Path | What it is |
  435. | --- | --- |
  436. | `.mellos/map.json` | the default page — optional; a project whose work lives on named pages has none |
  437. | `.mellos/pages/<slug>.json` | one file per named page |
  438. | `.mellos/config.json` | the project's mapping policy (see [Setup](#setup-choose-when-maps-open)) |
  439. | `.mellos/focus` | one-shot "show this page" request from a launcher to a running pane; the pane consumes it and deletes it within a poll tick |
  440. | `.mellos/quit` | one-shot "close yourself" request from the `mmap` toggle, consumed and deleted the same way |
  441. | `.mellos/viewers/<pid>.json` | one report per live pane — the page it is showing, whether auto-follow is on — refreshed every second while it runs (see [Who is watching](#who-is-watching)) |
  442. | `<any of the above>.<pid>.<random>.tmp` | a save in flight; it is renamed over its target or removed. A leftover means a write failed (and was reported) and even its cleanup could not run |
  443. | `.mellos/.write-lock` | permanent regular file for the OS project lock; keep it untracked and never remove, rename or replace it during normal operation |
  444. The map files are plain JSON, safe to commit if you want the maps' history in
  445. git. Keep `focus`, `quit`, `viewers/` and `.write-lock` out of Git. The first
  446. three carry runtime messages; the lock file must remain in place, including
  447. when no process holds its lock.
  448. **Concurrency, stated plainly.** Every save is atomic — written to a private
  449. sibling temp file and renamed over the target — so a reader polling the store
  450. sees the previous complete map or the new one, never a torn write. Every graph
  451. writer (MCP, the HTTP viewer, the watcher) uses the same non-blocking OS
  452. exclusive lock for the project. The lock has its own fixed file, separate from
  453. the map files being replaced; it stays in place after the OS releases the lock
  454. on completion or process exit. Contention returns a retryable `BUSY`.
  455. The lock serializes each operation's read, change and save. To protect an edit
  456. computed from an earlier read, pass `expectedRevision`: it is compared inside
  457. the lock, and a stale revision returns `CONFLICT`. Without it, a later write
  458. can still overwrite the same field or a whole value such as `context`. Pages
  459. separate unrelated efforts; sharing a page still requires revision-checked
  460. edits. Low-level `saveMapFile`, hand edits and older running processes do not
  461. participate in this contract. Stop all old MCP, viewer and watcher processes
  462. for the project before upgrading; an old lock directory needs a one-time
  463. migration. See the [persistent-map API guide](docs/map-api.md) and
  464. [project locking](docs/locking.md) for the boundary and upgrade steps.
  465. ### Diagram kinds
  466. The default kind, `dev`, is the living progress ledger described above. The
  467. same layered-DAG machinery also draws documentation diagrams: pass `kind`
  468. in `mmap_declare` and the page renders neutrally — plain solid boxes, no
  469. ghosts, no spinners, no progress counts.
  470. | Kind | Reading | Extras |
  471. | --- | --- | --- |
  472. | `architecture` | layered components (also module deps, call graphs) | edge labels for protocols |
  473. | `dataflow` | pipeline stages as layers, sources at the bottom | edge labels for the data |
  474. | `behavior-tree` | leaves (actions) at the bottom, root on top (also mind maps, WBS) | node kinds `selector` `sequence` `parallel` `decorator` `condition` `action` render as glyphs |
  475. | `sequence` | classic call/return: time flows top-down, participants as lane headers; every call and every return is an event in the acting participant's lane | `lanes` are participants; edge labels are messages |
  476. Node kinds and edge labels work on `dev` maps too. State machines are out
  477. of scope on purpose: transitions cycle, and edges here only point downward.
  478. ### Sub-maps
  479. A node can link a child page with `submap: <page-slug>` — the pane badges it
  480. `⊞`; double-click dives into the child map, `Backspace` climbs back out. A
  481. map of maps, built entirely from pages: no new storage, no new invariants.
  482. Whether a node deserves a sub-map is the AI's judgment call — most don't.
  483. Sub-maps are interior detail, not siblings: a page some *other* page dives
  484. into never occupies a tab. Two refinements keep the tab strip from erasing
  485. itself — a page whose own node names itself hides nobody, and a link cycle
  486. keeps its tabs unless a page outside the cycle dives in, because a cycle has
  487. no outside to climb back to. Inside a dive the tab row becomes a breadcrumb —
  488. `⌫ parent map ▸ node` — and clicking it (or `Backspace`) climbs back out.
  489. When a hidden sub-map changes in the background, the footer says so.
  490. ## MCP tools
  491. Start with `mmap_read` to resume an existing page; a new conversation is not a
  492. new effort. Use stable IDs, filtered reads and revision-checked writes. The
  493. [persistent-map API guide](docs/map-api.md) covers complete CRUD, atomic mixed
  494. batches, context checkpoints, source hashes and worktree boundaries.
  495. | Tool | Purpose |
  496. | --- | --- |
  497. | `mmap_declare` | Grow the map: title (`null` removes it), diagram kind, layer bands, lanes, groups (subsystems), nodes — with `status`, `evidence`, `detail`, `kind`, `group`, `lane`, `submap` — and edges, optionally labeled (all-or-nothing batch) |
  498. | `mmap_update` | Record progress **and revise**: status (`planned → in-progress → done` +evidence, `regressed`), relabel a node, move it to another band (`layer`), join/leave a group or lane, set a node kind or a `submap`; rename and re-rank bands (`layers`), relabel groups (`groups`) and lanes (`lanes`); `null` clears any clearable field |
  499. | `mmap_remove` | Revise: drop edges, nodes, groups, lanes, empty bands — and, with `pages`, whole pages, file and all (permanent; applied after this call's map edits) |
  500. | `mmap_view` | Render the current map as text inline (optional `zoom`, `-4`…`2`), ending with a `pages:` line naming every page the project has and which one you are looking at |
  501. | `mmap_read` | Structured page discovery, precise IDs, filtered/paginated reads, context and source changes |
  502. | `mmap_batch` | One-page mixed create/update/remove transaction with a revision check |
  503. | `mmap_setup` | Get/set the project's mapping policy — when maps open |
  504. | `mmap_open` | Put the map on your screen: open the pane, or retarget an open one to a `page` (`window: true` for the dedicated window). It answers with whether a pane actually reported in afterwards, not merely that a command ran — and it can never close one |
  505. A batch applies bands → groups → lanes → node updates, and within one node
  506. update `layer` moves the node before its other fields, so a node can move and
  507. join a group on its new band in one item.
  508. What the boundary refuses, so the ledger never records something it did not
  509. mean:
  510. - **an unknown key**, naming it — a misspelled `evidance` is an error, not a
  511. silently dropped field, at every nesting depth;
  512. - **control characters** in text fields — an ESC sequence stored in a label
  513. would let a map repaint the terminal of everyone who opens it. `detail` is
  514. the exception: newlines and tabs are how a note is written, everything else
  515. (ESC, BEL, lone CR) is still refused. File loading and library saves apply
  516. the same control-character rules, retaining multiline evidence in older
  517. files. Terminal rendering also neutralizes controls in maps constructed
  518. directly by library callers;
  519. - **an empty string** where a field is optional — `null` is how a field is
  520. cleared, never a blank that renders as a box nobody can tell from a real
  521. one;
  522. - **a node whose `submap` names the page the call itself targets** — a link
  523. with no bottom, not a parent link;
  524. - **a page deletion aimed at the page the same call targets, or at a slug the
  525. project does not have** — one call must not edit a map it is deleting, and
  526. a name matching no page is a typo far more often than a race; the refusal
  527. lists the pages that do exist.
  528. A write that does not land answers `save failed, nothing changed (retry)`:
  529. the previous file is intact and calling again is the whole recovery.
  530. ### Who is watching
  531. A map nobody has on screen is a file, not a map — and nothing in the system
  532. used to be able to tell the difference. An assistant would declare a design,
  533. light nodes up as it built them, and report all of it into a store you had
  534. never opened a pane for.
  535. Every pane now publishes a small report while it runs — `.mellos/viewers/`,
  536. one file per pane, refreshed once a second — and every write and every view
  537. ends with what those reports say:
  538. | The line | What it means |
  539. | --- | --- |
  540. | `pane: CLOSED` | nobody is seeing this map; the assistant opens one with `mmap_open` instead of asking you to |
  541. | `pane: running on this page` | a live process reports this page; its terminal may be hidden |
  542. | `pane: open on <other>, auto-follow on` | the pane follows the page last written, so it arrives here by itself |
  543. | `pane: open on <other>, auto-follow OFF` | you pinned that page by hand: the change is real and NOT on your screen. The assistant is told to say so rather than move your view |
  544. The same reports answer "is a pane already open?" for `mmap` and for the
  545. launcher — a question that used to cost a Windows-only process scan and could
  546. not say which page was on screen. A report whose pane stopped refreshing it is
  547. ignored after five seconds and deleted after a minute, so a killed pane cannot
  548. go on claiming an audience.
  549. A heartbeat does not establish screen visibility. An explicit tmux open also
  550. selects the existing watcher's window, reveals it if another pane was zoomed,
  551. and verifies the attached session's active window before reporting visibility.
  552. Focusing that watcher in a shell without `TMUX` reuses its original owner.
  553. ### Setup: choose when maps open
  554. How eager mapping should be is a habit, not a property of a repository — so it
  555. is chosen **once, for you**, in the first session after you install:
  556. - `always` — map every structured task: workflows, designs, architecture,
  557. technical dependencies. The assistant opens the pane on its own initiative;
  558. your recorded answer is its standing consent, so it stops asking.
  559. - `complex` — the same, but only for medium or complex tasks: several modules,
  560. a new subsystem, roughly an hour of work or more.
  561. - `on-request` — map only when you explicitly ask. In a project with no map,
  562. the plugin then says nothing at all — zero noise is the point.
  563. The answer lands in `<your home>/.mellos/config.json` and reaches every session
  564. through the plugin's `SessionStart` hook, which reads it and hands the
  565. assistant the matching instruction before you have typed anything. Nothing has
  566. to be set up per project, ever again.
  567. One project can still differ: `mmap_setup {policy, scope: "project"}` records
  568. a policy in that project's `.mellos/config.json`, and a project policy
  569. overrides the user one. `/mmap setup` re-runs the question for either scope
  570. whenever you want to change your mind. The policy guides the assistant; it
  571. never blocks the tools, and asking for a map explicitly always works under any
  572. policy.
  573. Hosts without hooks (Codex CLI, a bare MCP client) get the question another
  574. way: while no policy exists in either scope, every `mmap_declare` reply carries
  575. a note telling the assistant to ask you. That note goes quiet for good — in
  576. every project — the moment you have answered anywhere.
  577. Structural invariants enforced by the tools: layers form a total order by
  578. rank (an integer in 0..99, 0 = bottom, unique per map); every node lives in
  579. exactly one layer; edges point **strictly downward** — which makes the graph
  580. acyclic by construction; nodes may not depend on same-layer siblings (if A
  581. needs sibling B, either B is really a lower concept or A and B are one node);
  582. a group clusters nodes within one band; and node ids and group ids share
  583. **one namespace** — an id names a node or a group, never both, because both
  584. render as boxes and one id must mean one box.
  585. ## Development
  586. See [contributing](CONTRIBUTING.md) and the
  587. [project structure, branch and recovery guide](docs/project-maintenance.md).
  588. ```
  589. npm ci
  590. npm run verify
  591. ```
  592. Use Node.js 22.12+ for development. `verify` runs `typecheck`, `test`, `build`
  593. (bundles `dist/` and emits `lib/` with declarations), `check:package`,
  594. `check:codex`, and `check:release`. These check npm entrypoints, the Codex
  595. package and both installable editions, including their MCP handshake.
  596. The repo is itself layered bottom-up, and each layer has its spec:
  597. | Layer | Code | Spec | Owns |
  598. | --- | --- | --- | --- |
  599. | 0 domain | `src/domain/` | `ops.test.ts` | the map value, structural invariants, pure ops |
  600. | 1 format | `src/store/format.ts` | `store.test.ts` | the state-file format: replay-validated parse, serialize — I/O-free |
  601. | 1 store | `src/store/store.ts` | `store.test.ts`, `atomic-save.test.ts` | atomic state-file persistence on Node |
  602. | 1 semantics | `src/semantics/` | `semantics.test.ts` | medium-neutral view semantics: zoom ladder, group aggregation, page-set rules, sequence flip, the shared glyph vocabulary |
  603. | 2 apply | `src/server/apply.ts` | `apply.test.ts` | tool inputs → transactional op sequences |
  604. | 3 server | `src/server/server.ts` | `server.test.ts`, `save-failure.test.ts` | the eight MCP tools over stdio |
  605. | 4 render | `src/render/` | `render.test.ts`, `routing.test.ts` | the ASCII renderer and its wire routing |
  606. | 4 pane | `src/watch/` | `watch.test.ts`, `pane-state.test.ts`, `input.test.ts` | the polling pane: page set, input parsing, panel and chrome |
  607. | — launchers | `scripts/` | `open-pane.test.mjs`, `codex-register.test.mjs` | plain-node entry points |
  608. | — packaging | `package.json` | `tests/lockfile.test.ts`, `browser-safe.test.ts` | what ships, and to whom |
  609. `dist/` is committed deliberately: plugin installation clones this repo and
  610. runs nothing, so entry points ship bundled. CI diffs the committed `dist/`
  611. against a fresh build, so a source change that forgets the rebuild fails.
  612. ### Library
  613. The lower layers are also a library (`npm run build` emits `lib/` with type
  614. declarations; npm packs it). Subpath exports mirror the source:
  615. | Subpath | Contents | Browser-safe |
  616. | --- | --- | --- |
  617. | `mellos-mapping/domain/types` | the map value, ids, ranks, statuses, errors | yes |
  618. | `mellos-mapping/domain/ops` | pure operations over a map | yes |
  619. | `mellos-mapping/format` | state-file parse / serialize, page ids | yes |
  620. | `mellos-mapping/semantics` | zoom ladder, group aggregation, focus and page-set rules, the shared glyph vocabulary | yes |
  621. | `mellos-mapping/render` | the terminal renderer | gated the same way (it is pure), but its output is character cells — for terminal hosts |
  622. | `mellos-mapping/store` | filesystem persistence, atomic saves, focus file, policy | Node only |
  623. | `mellos-mapping/server` | the bundled MCP server entry — a spawn target, not a module to import | Node only |
  624. **Browser-safe** means no Node builtins anywhere in the import closure, gated
  625. by a test, so a graphical client (a web panel, an editor view) can parse state
  626. files and reuse the exact aggregation, zoom and glyph semantics the terminal
  627. pane draws with.
  628. ## Optional GitHub Star reminder
  629. npm/npx installations may show one small, dismissible reminder after at least
  630. 7 days and successful map viewing on 3 different UTC dates. Web viewers show
  631. it inline without taking focus; a native interactive terminal shows it only
  632. after a successful viewing session exits. It is never added to MCP replies,
  633. AI prompts, install logs, CI or piped output. Plugin editions and source
  634. checkouts are excluded.
  635. The reminder is claimed once per user, across projects, versions and installs.
  636. The Star button opens GitHub in the system's default browser, keeping its
  637. existing sign-in session. A failed launch leaves the notice open with a copy-address option.
  638. Closing it, following its Star link, or simply leaving the session means it
  639. will not appear again. To suppress it before it appears, set
  640. `MELLOS_MAPPING_NO_STAR=1` in the environment of the viewer/MCP process.
  641. Only the first-use time, last UTC day, a capped day count and the one-time flag
  642. are stored in `~/.mellos/support/star-reminder.json`; nothing is uploaded and
  643. GitHub is contacted only when the user follows the link. Unreadable settings
  644. or a busy store silently skip the reminder.
  645. ## Community
  646. This project takes part in and endorses the
  647. [LINUX DO](https://linux.do) community.
  648. ## License
  649. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.