GuangminJu/mellos-mapping
A live layered dependency map for bottom-up development — MCP server + terminal pane for Claude Code, Codex CLI and any MCP client. Ghost the design first, light nodes up as they are built and verified.
安装Install
dsh plugin --profile web add github:GuangminJu/mellos-mapping把 GuangminJu/mellos-mapping 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
Mellos Mapping
English | 简体中文
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/<version>/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 <plugin root>/scripts/open-pane.mjs <project dir> — it splits the
terminal window hosting the session (or falls back to a dedicated
"mellos-mapping" window; --window picks that on purpose). Add
--page <slug> 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 <plugin root>/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
- Ask Claude to build something non-trivial. The bundled skill has Claude declare the ghost design and keep the map current as it works.
- Run
/mellos-mapping:mmapto 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--windowto put the map in its own dedicated window instead. Prefer--asciiif your font lacks box-drawing glyphs. - 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/2with 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/<page>.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: <page-slug> — 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
相关推荐Related
-
nexu-io/open-design
🎨 Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. 🖥️ Local-first desktop app. 🖼️ Your…
-
esengine/DeepSeek-Reasonix
DeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.
-
Molunerfinn/PicGo
:rocket: The Ultimate Image Uploader for Efficient Creators. Supports Obsidian, Typora, VS Code etc. and 60+ image hosti…
-
anywhere-labs/deepseek-harness-desktop
为 DeepSeek Harness (DSH) 插件生态打造的现代化桌面端解决方案。万物皆「插件」，桌面本身也是「插件」。
-
tt-a1i/archify
Agent skill for beautiful, verifiable architecture, workflow, sequence, data-flow, and lifecycle diagrams—self-contained…
-
freestylefly/awesome-gpt-image-2
Prompt as Code | GPT-Image2 工业级提示词引擎与模板库，470+ 个案例逆向工程，20+ 套工业级模板，并提炼出Skills，持续更新中
-
YaoApp/yao
✨ All your agents and workspaces in one place, on every device you own. Track tasks on a board, accessible from desktop,…
-
ZSeven-W/openpencil
The world's first open-source AI-native vector design tool and the first to feature concurrent Agent Teams. Design-as-Co…