A live, terminal-native map of bottom-up development for Claude Code and Codex CLI.
While Claude builds your system, a split pane beside the conversation shows
the system's **layered dependency map**: primitive layers at the bottom,
dependency edges that may only point downward, ghost nodes for what is
designed, a spinner on what is being built right now, and solid green for
what is built *and verified*.
```
Mellos Mapping · the plugin itself
━━━━━━━━━━━━━━━━━━━━━━━━━━ orchestration
╭╌╌╌╌╌╌╌╌╌╌╌╌╌╌╮
╎ · MCP Server ╎
╰╌╌╌╌┬╌┬╌╌┬╌╌╌╌╯
│ │ │
└─┼──┼─────────────┐
│ └──────┐ │
│ │ │
━━━━━━━━━┿━━━━━━━━━┿━━━━━━┿━━━ contracts
│ │ │
┏━━━━━━┷━━━━━━━━┓│ ╭╌╌╌╌┴╌╌╌╌╌╌╮
┃ ■ State Store ┃│ ╎ · Watcher ╎
┗━━━━━┯━━━━━━━━━┛│ ╰╌╌╌╌╌┬╌╌╌╌╌╯
│ │ │
│ ┌────────┘ │
│ │ │
━━━━━━━━┿━┿━━━━━━━━━━━━━━━━┿━ primitives
│ │ │
┏━━━━━┷━┷━━━━━━┓ ╭──────┴───────────╮
┃ ■ Map Domain ┃ │ ⠋ ASCII Renderer │
┗━━━━━━━━━━━━━━┛ ╰──────────────────╯
· planned ⠋ in-progress ■ done ✗ regressed
```
In a real terminal the wiring and band bars render FAINT while node boxes
glow in their status colors with bold labels — a dark circuit board where
the components are the bright things. Skip-level edges thread through gaps
between boxes (watch the line dive between State Store and Watcher above);
non-overlapping wire segments share track rows to keep the bands close.
*(This is the plugin's own map, mid-development. The spinner really spins.)*
## Why
Most progress reporting is a task list — a top-down worldview. A Mellos map
grows the other way: an upper node can only stand on nodes below it, and the
picture makes the discipline visible:
- **The ghost design appears before any code.** Claude declares the whole
intended structure as dashed ghost nodes first; you can veto a bad design
while it is still only a picture.
- **The spinner is where Claude's attention is.** One glance answers "what is
it doing right now, and on top of what?"
- **Done means verified.** A node turns solid green only with evidence (a
passing test run). If later work cracks a foundation, the node turns red —
a cracked foundation under a spinning upper floor is the most honest status
report there is.
- **The map is a ledger, not a judge.** The tools refuse only structural
corruption (an edge pointing upward, a duplicate rank). Workflow is
Claude's discipline, defined in the bundled skill; violations are made
*visible*, never silently blocked.
## Install
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 Node.js 18+ on PATH (Claude Code itself requires Node, so you
already have it). No build step: the MCP server and watcher ship pre-bundled.
## Update
```
claude plugin marketplace update mellos-mapping && claude plugin update mellos-mapping@mellos-mapping
```
Two steps because `plugin update` compares against the locally cached
marketplace clone — the first command is what actually pulls this repo.
Restart Claude Code to apply. Releases are version bumps on `master`.
(In-app, `/plugin` opens the same management UI.)
## Codex CLI
The same repo doubles as a Codex plugin (codex-cli 0.147+). Three lines:
```
codex plugin marketplace add GuangminJu/mellos-mapping
codex plugin add mellos-mapping@mellos-mapping
node ~/.codex/plugins/cache/mellos-mapping/mellos-mapping//scripts/codex-register.mjs
```
The first two install the skill (the map discipline) as a Codex plugin. The
third registers the MCP server at user level — needed because Codex spawns
plugin-bundled MCP servers inside the plugin cache with no way to see your
workspace, so a bundled server would write the map into the cache. A
user-level `codex mcp add` entry (which the script writes) inherits each
session's working directory instead: the state file lands in your project,
same as under Claude Code. The registered path is version-specific — re-run
the script after updating the plugin.
To watch the live pane beside a Codex session on Windows, run
`node /scripts/open-pane.mjs ` — it splits the
terminal window hosting the session (or falls back to a dedicated
"mellos-mapping" window; `--window` picks that on purpose). Add
`--page ` to open on a particular page — and with a pane already open,
rerunning with `--page` retargets it instead of opening another. The pane
auto-follows the page being written — the map the agent is operating on
right now; press `f` to toggle that (a manual page switch also turns it
off), or start with `--no-follow`. Elsewhere run
`node /dist/watch.mjs` (same `--page` / `--no-follow` flags)
from the project directory in a second terminal (or any terminal split).
## Any MCP client
The server ships on npm, so any MCP client (Cursor, Windsurf, Zed,
Gemini CLI, …) can run it with a standard stdio entry:
```
npx -y mellos-mapping
```
The map file lands in the client session's working directory
(`.mellos/map.json`). Open the live pane from the same project:
```
npx -y -p mellos-mapping mellos-mapping-watch
```
The skill/discipline layer is Claude Code + Codex specific; other clients
get the four `mmap_*` tools and the pane, and bring their own prompting.
## Use
1. Ask Claude to build something non-trivial. The bundled skill has Claude
declare the ghost design and keep the map current as it works.
2. Run `/mellos-mapping:mmap` to open the live pane (Windows Terminal split
on Windows, tmux split inside tmux, or a printed command to run in any
second terminal). On Windows the pane opens in the terminal window
hosting YOUR session, even with several windows open; pass `--window` to
put the map in its own dedicated window instead. Prefer `--ascii` if
your font lacks box-drawing glyphs.
3. Watch nodes light up from the bottom. Interrupt when the picture worries
you — that is what it is for.
The pane is mouse-aware (xterm SGR any-event tracking — the same protocol
htop and tmux speak):
| Input | Action |
| --- | --- |
| hover a node | spotlight its wires; preview its details below the map |
| click a node | pin it — details stay resident after the mouse leaves |
| click empty space / `Esc` | unpin; with nothing pinned, `Esc` climbs out of a dive |
| wheel / `+` `-` | zoom, anchored on the focused node (see the ladder below) |
| left-drag | grab and pan when the map outgrows the pane |
| shift+wheel | scroll vertically |
| `hjkl` / arrows | nudge the view |
| `Tab` / `Shift+Tab` / `1-9` / click a tab | switch pages (parallel maps) |
| double-click a `⊞` node | dive into its sub-map (a child page) |
| `Backspace` / `Esc` | climb back out of the last dive |
| drag the `⋯` divider | resize the detail panel — pull it up to read long design notes in full |
| `0` | reset pan and zoom |
| `q` | quit the pane |
Zooming scales the picture first and switches display mode only at the ends
of the ladder, so every level still shows meaningful data:
```
detail ← 100% ← 85% ← 70% ← 55% ← overview
```
- **zoom in past 100%** — evidence and design notes unfold inside the boxes;
- **85–55%** — whitespace tightens and labels truncate proportionally, boxes
stay boxes;
- **below 55%** — labels would stop meaning anything, so the map AGGREGATES:
each declared group (a labeled subsystem within a band) becomes one box
named `foundation subsystem 1/2` with its status derived from the members, edges
collapse onto the groups, ungrouped nodes stay themselves. Like a real
map, zooming out shows province names — not anonymous dots. (A map with
no groups falls back to a pure glyph constellation with per-band counts.)
The footer always names the level.
The two detail rows live at a fixed spot between map and hint line, showing
the focused node's status, layer, evidence and both wire directions
(`uses → … · used by ← …`) — nothing ever floats over the map.
`--no-mouse` disables mouse reporting if your terminal multiplexer wants the
mouse for itself.
### Pages
A project can keep several maps side by side — **one effort = one page**.
Claude targets a page by passing `page` to any `mmap_*` tool; the pane grows
a tab bar as soon as a second page exists. The active tab is bold in its
map's aggregate status color; when a background page's file changes, its tab
lights up in status color instead of stealing your view. Each page remembers
its own pan, zoom and pinned node. Because every page is its own file, two
Claude sessions writing two pages can never clobber each other — this is
also the answer to running several Claude sessions in one project.
State lives in `.mellos/map.json` (the default page) plus
`.mellos/pages/.json` for named pages — plain JSON,
safe to commit if you want the maps' history in git.
### Diagram kinds
The default kind, `dev`, is the living progress ledger described above. The
same layered-DAG machinery also draws documentation diagrams: pass `kind`
in `mmap_declare` and the page renders neutrally — plain solid boxes, no
ghosts, no spinners, no progress counts.
| Kind | Reading | Extras |
| --- | --- | --- |
| `architecture` | layered components (also module deps, call graphs) | edge labels for protocols |
| `dataflow` | pipeline stages as layers, sources at the bottom | edge labels for the data |
| `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 |
| `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 |
Node kinds and edge labels work on `dev` maps too. State machines are out
of scope on purpose: transitions cycle, and edges here only point downward.
### Sub-maps
A node can link a child page with `submap: ` — the pane badges it
`⊞`; double-click dives into the child map, `Backspace` climbs back out. A
map of maps, built entirely from pages: no new storage, no new invariants.
Whether a node deserves a sub-map is the AI's judgment call — most don't.
Sub-maps are interior detail, not siblings: a page referenced as a submap
never occupies a tab. Inside a dive the tab row becomes a breadcrumb —
`⌫ parent map ▸ node` — and clicking it (or `Backspace`) climbs back out.
When a hidden sub-map changes in the background, the footer says so.
## MCP tools
| Tool | Purpose |
| --- | --- |
| `mmap_declare` | Grow the map: title, diagram kind, layer bands, lanes, groups (subsystems), nodes, edges — optionally labeled (all-or-nothing batch) |
| `mmap_update` | Record progress: `planned → in-progress → done` (+evidence), `regressed`, group/lane membership, node kind |
| `mmap_remove` | Revise: drop edges, nodes, groups, lanes, empty bands |
| `mmap_view` | Render the current map as text inline (optional `zoom`) |
| `mmap_setup` | Get/set the project's mapping policy — when maps open |
### Setup: choose when maps open
Each project chooses how eager mapping is, once, via `/mmap setup` (or the
first time the assistant declares a map — the reply nudges it to ask you):
- `always` — map every structured task: workflows, designs, architecture,
technical dependencies.
- `complex` — map only medium or complex tasks (the default until configured).
- `on-request` — map only when you explicitly ask.
The choice is stored in `.claude/mellos-mapping.config.json` and guides the
assistant; it never blocks the tools, and asking for a map explicitly always
works under any policy.
Structural invariants enforced by the tools: layers form a total order by
rank; every node lives in exactly one layer; edges point **strictly
downward** — which makes the graph acyclic by construction; nodes may not
depend on same-layer siblings (if A needs sibling B, either B is really a
lower concept or A and B are one node).
## Development
```
npm install
npm run verify # typecheck + tests + bundle
```
The repo is itself layered bottom-up, and each layer has its spec:
| Layer | Code | Owns |
| --- | --- | --- |
| 0 domain | `src/domain/` | the map value, structural invariants, pure ops |
| 1 format | `src/store/format.ts` | the state-file format: replay-validated parse, serialize — I/O-free |
| 1 store | `src/store/store.ts` | atomic state-file persistence on Node |
| 1 semantics | `src/semantics/` | medium-neutral view semantics: zoom ladder, group aggregation, sequence flip |
| 2 apply | `src/server/apply.ts` | tool inputs → transactional op sequences |
| 3 server | `src/server/server.ts` | the four MCP tools over stdio |
| 4 render | `src/render/`, `src/watch/` | ASCII renderer and the polling pane |
`dist/` is committed deliberately: plugin installation clones this repo and
runs nothing, so entry points ship bundled.
### Library
The lower layers are also a library (`npm run build` emits `lib/` with type
declarations; npm packs it). Subpath exports mirror the source:
`mellos-mapping/domain/types`, `/domain/ops`, `/format`, `/semantics` are
**browser-safe** — no Node builtins in their import closure, gated by a test —
so a graphical client (a web panel, an editor view) can parse state files and
reuse the exact aggregation and zoom semantics the terminal pane draws with.
`/store` (Node filesystem persistence) and `/render` (the terminal renderer)
complete the surface for Node hosts.
## License
MIT
