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: 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).

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 is no per-project setup step. See Setup: choose when maps open.

The mmap terminal command (the pane's open/close toggle) installs itself on Windows: the same hook notices on session start when the shim is missing or points at an older install, writes mmap.cmd (cmd, PowerShell) and mmap (git-bash) into %LOCALAPPDATA%\mellos-mapping\bin, appends that one directory to your user PATH, and tells you so through the assistant. The PATH change reaches only new processes — and a new tab of a running Windows Terminal inherits the old environment, so close the terminal app entirely and reopen it before the first mmap. The PATH edit keeps the installer's guarantees: nothing happens when the entry is already there, and a PATH that setx would damage (flattened %VARIABLE% references, truncation past its limit) is refused outright, with the entry to add by hand named instead.

The step behind it is still a command of its own, for the cases the hook does not cover — --uninstall, or re-adding a PATH entry you removed while the shims stayed put:

node "<plugin dir>/scripts/install-mmap-command.mjs" [--uninstall]

(--json prints the install outcome as one JSON line instead of prose — the mode the hook itself calls it in.) npm i -g mellos-mapping provides the same mmap via bin, no shims involved.

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.)

Upgrading from 0.19

0.20 moved the store out of .claude/ — the map belongs to this tool, not to one client — into .mellos/. The server and the watcher each perform the move once at startup, and print exactly one line on stderr when they do (mellos-mapping: moved the legacy .claude map store to .mellos/ — commit the move.):

Nothing is merged and nothing is overwritten: a project that already has a .mellos/ store (map, pages or config) is left untouched, whatever the legacy directory still holds. If you keep your maps in git, commit the move — git add -A .claude .mellos records it as renames rather than as a pile of deletions plus untracked files.

That one move is the only time either process touches .claude/. Afterwards the tools write nowhere but .mellos/, and never outside the project directory they resolved at startup.

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 from the project directory in a second terminal (or any terminal split). Both take the same flags — see Pane flags.

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 server picks its project directory in this order: MELLOS_MAPPING_CWD (an explicit override, for clients that spawn servers from a fixed directory), then CLAUDE_PROJECT_DIR (what Claude Code sets for plugin MCP servers), then the server process's own working directory. Set MELLOS_MAPPING_CWD when your client would otherwise start the server somewhere other than the project you are working in.

The skill/discipline layer is Claude Code + Codex specific; other clients get the five mmap_* tools and the pane, and bring their own prompting.

Use

Read the full README on GitHub →