mellos-mapping

# Mellos Mapping

[![CI](https://github.com/GuangminJu/mellos-mapping/actions/workflows/ci.yml/badge.svg)](https://github.com/GuangminJu/mellos-mapping/actions/workflows/ci.yml)

English | [简体中文](README.zh-CN.md)

A live, terminal-native map of bottom-up development for
[Claude Code](https://claude.com/claude-code) and Codex CLI.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: light)" srcset="docs/demo-light.svg">
    <img alt="A Mellos map building itself: ghost design first, spinners climbing the layers, a cracked foundation spreading upward, honest recovery" src="docs/demo.svg" width="620">
  </picture>
</p>

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](#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.`):

| 0.19 and earlier | 0.20 and later |
| --- | --- |
| `.claude/mellos-mapping.json` | `.mellos/map.json` |
| `.claude/mellos-mapping.pages/` | `.mellos/pages/` |
| `.claude/mellos-mapping.config.json` | `.mellos/config.json` |

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](#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

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. The pane opens itself. Every write tells Claude whether anybody is
   actually looking (see [Who is watching](#who-is-watching)), and Claude
   opens or retargets the pane with `mmap_open` when nobody is — you never
   have to remember to. Open or close it yourself with `mmap` in a