mellos-mapping

Mellos Mapping

English | 简体中文

Claude Code、ChatGPT デスクトップの Codex モード、Codex CLI 向けの、ボトムアップ開発をリアルタイムに表示するターミナルネイティブなマップです。

Claude がシステムを構築している間、会話の横にある分割ペインにシステムの階層型依存関係マップが表示されます。最下部にはプリミティブなレイヤーがあり、依存関係のエッジは下向きにしか伸ばせません。設計済みのノードはゴースト表示で、現在構築中のノードにはスピナーが表示され、構築と検証が完了したノードは緑色で塗りつぶされます。

実際のセッション：左側が Claude Code、右側がマップペインです。L0 は検証済みで、L1 は点灯したばかり、上位はすべてまだゴースト表示です。

Why

ほとんどの進捗報告はタスクリストであり、トップダウンの世界観に基づいています。Mellos のマップは反対に成長します。上位のノードは下位のノードの上にしか配置できず、その図によって規律が見えるようになります。

• ゴースト設計はコードより先に表示されます。 Claude はまず、意図する構造全体を破線のゴーストノードとして宣言します。設計がまだ図だけの段階で、問題のある設計を却下できます。
• スピナーは Claude が注目している場所を示します。 ひと目見るだけで、「今何をしていて、その作業は何を土台にしているのか」が分かります。
• 完了とは検証済みであることを意味します。 証拠（テスト実行の成功）がある場合にのみ、ノードは緑色で塗りつぶされます。その後の作業で基盤にひびが入ると、ノードは赤色になります。回転中の上層階の下で基盤にひびが入っている状態ほど、正直な進捗報告はありません。
• マップは台帳であり、裁判官ではありません。 ツールが拒否するのは、構造の破損（上向きのエッジ、重複したランク）だけです。ワークフローは、同梱されたスキルで定義される Claude の規律に委ねられています。違反は黙って阻止されるのではなく、可視化されます。

Install

ホストに対応するブランチをクローンし、コマンドをひとつ実行してください。ビルドは不要です。

ブランチ	対象	クローン後に実行するコマンド
main	共通ソース／どちらのホストにも対応	node install.mjs chatgpt-app または node install.mjs claude
claude	Claude Code	node install.mjs
chatgpt-app	ChatGPT デスクトップ、Codex モード	node install.mjs
18.x 系では Node.js 18.17 以降、または 20.3 以降と、対応するホスト CLI が PATH 上に必要です。対応プラットフォームは Windows 10 以降、macOS 13.0 以降、glibc 2.28 以降の Linux で、それぞれ x64 または arm64 です。OS は、選択した Node.js バージョンの要件も満たす必要があります。ネイティブロックバインディングはリリースに同梱されているため、ローカルでのコンパイルは不要です。インストーラーはリリースの整合性と 8 つすべての MCP ツールを確認し、ランタイムをクローンの外に保持して、ホストを設定します。インストール後、新しい会話を開始してください。リリースとブランチの手順を参照してください。

Claude Code のマーケットプレイスからインストールすることもできます。

Claude Code の会話内で、次の 2 行を実行します。

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

または、ターミナルで次の 1 行を実行します。

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

PATH 上に、同じNode.js とプラットフォームのバージョンが必要です（ネイティブ版の Claude Code を使用する場合は、Node を別途インストールしてください）。ビルド手順はありません。dist/ はコミット済みのため、クローンはそのまま実行できます — dist/server.mjs（MCP サーバー）、dist/watch.mjs（ペイン）、 dist/mmap.mjs（mmap の切り替え）、dist/hook-session-start.mjs（hooks/hooks.json が登録する SessionStart フック）、および dist/store-paths.mjs（ストアのパス語彙。プレーンな Node で動作するペインランチャーがファイル名を再記述する代わりにインポートします）。

omp（Oh My Pi） は、Claude Code 版に同梱されるものと同じプラグインレイアウトを読み込みます — 同じマーケットプレイスカタログ、.mcp.json、スキル、スラッシュコマンドを使用するため、1 つのリリースで両方のホストに対応できます。

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

このインストール方法では main を追従します。リリース時にはバージョンが更新されます。特定のバージョンに固定するには、次のいずれかを追加でチェックアウトしてください。GitHub Release の Claude Code 版 ZIP、またはリリースタグを指定したクローンです。

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

omp は hooks/hooks.json を読み込まないため、セッションの説明はプラグインの omp ホストアダプター（package.json#omp.extensions で宣言される dist/omp-extension.mjs）を介して届きます。ストア、ポリシーテキスト、mmap シムは、Claude のフック版と同じものがインストールされます。ペインは、セッションの横に表示される同じターミナル分割です。プラグインとしてインストールしてください。omp plugin link も npm パッケージもプラグインではなく、どちらを使ってもツールがインストールされません。omp のインストールと制限事項を参照してください。

pi はこのレイアウトを一切読み込みません。設計上、拡張機能を読み込み、独自の MCP は持ちません。そのため、このプラグインは自身に対して MCP を使用します。package.json#pi.extensions で宣言されている拡張機能（dist/pi-extension.mjs）が、セッションのディレクトリで同じ dist/server.mjs を起動します。これにより、8 つの mmap_* ツールは同じ名前で同じ 8 つとなり、セッションの説明は Claude のフックが出力するものと同じストアとポリシーテキストから生成されます。

pi install npm:mellos-mapping

すべてのプロジェクトではなく、現在のプロジェクトにインストールするには -l を追加し、その後、新しいセッションを開始してください。pi はセッション開始時にパッケージを検出します。パッケージに含まれる skills/ と commands/ も一緒に読み込まれます。同じマップ運用に加え、同じスラッシュコマンドの /mmap を利用できます。pi のインストールと動作を参照してください。

インストール後の最初のセッションでは、マップをどれくらい積極的に開くかについて1 つだけ質問され、その回答が今後開くすべてのプロジェクトに記録されます。それ以降は、フックが各新規セッションに自動で設定を引き継ぐため、プロジェクトごとのセットアップは不要です。 セットアップ：マップを開くタイミングを選択するを参照してください。 mmap ターミナルコマンド（ペインの開閉切り替え）は、Windows では自動でインストールされます。同じフックがセッション開始時に shim が存在しない、または古いインストールを指していることを検知すると、%LOCALAPPDATA%\mellos-mapping\bin に mmap.cmd（cmd、PowerShell）と mmap（git-bash）を書き込み、そのディレクトリをユーザーの PATH に追加し、アシスタントを通じて通知します。PATH の変更が反映されるのは新しいプロセスだけです。実行中の Windows Terminal の新しいタブも古い環境を引き継ぐため、最初に mmap を実行する前にターミナルアプリを完全に終了して、再起動してください。PATH の編集ではインストーラーの保証が保たれます。エントリがすでに存在する場合は何も行わず、setx が損なう可能性のある PATH（%VARIABLE% 参照の展開や上限を超える切り捨て）は、そのまま拒否されます。

PATH の変更が拒否されても、行き止まりではありません。同じ 2 つの shim が %LOCALAPPDATA%\Microsoft\WindowsApps（または ~/.local/bin）に書き込まれます。このディレクトリはすでに PATH に含まれているため、PATH を変更せずに新しいターミナルで mmap を実行できます。PATH が長いマシンではまさにこの処理が行われ、最も重要な場面でも役立ちます。このコマンドには開くページを引数として指定します（mmap omp-host-support）。ページがすでに開いている場合は、ペインを閉じます。

この処理を担う手順は独立したコマンドとしても用意されています。フックが対応しないケース（--uninstall や、shim をそのままに PATH エントリを削除した後の再追加など）で使用します。

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

（--json を指定すると、インストール結果を説明文ではなく 1 行の JSON として出力します。フック自体もこのモードで呼び出します。）npm i -g mellos-mapping を実行すると、shim を介さずに bin 経由で同じ mmap を使用できます。

更新

claude plugin marketplace update mellos-mapping && claude plugin update mellos-mapping@mellos-mapping

plugin update はローカルにキャッシュされたマーケットプレイスのクローンと比較するため、2 つの手順が必要です。最初のコマンドで、このリポジトリを実際に取得します。反映するには Claude Code を再起動してください。リリースは main でバージョンを更新して行います。（アプリ内では、/plugin を実行すると同じ管理 UI が開きます。）

omp の更新も 2 つの手順で行います。

omp plugin marketplace update mellos-mapping && omp plugin upgrade mellos-mapping@mellos-mapping

まずペインを閉じてください（ペイン内で q を入力します）。ウォッチャーはプラグインのコピーから実行されます。また Windows では、開いているファイルの名前を変更できないため、ペインを開いたままアップグレードすると EPERM が発生し、プラグインのキャッシュが空になることがあります。その場合は omp plugin install mellos-mapping@mellos-mapping --force で修復できます。次に、最初のコマンドでカタログを更新し、2 つ目のコマンドでカタログから再インストールします。omp は起動時に、1 日更新されていないカタログ項目も更新します。ただし、marketplace.autoUpdate が off の場合は除きます。デフォルトの notify モードでは、このチェック結果はデバッグログにのみ記録されるため、更新を確認できる状態にするには marketplace update を実行します。upgrade はバージョンを比較しません。カタログに記載されたものを強制的に再インストールします。そのため、リリースはバージョン更新で識別され、それによって制限されることはありません。その後 omp を再起動し、古いバンドルが表示されたままのペインを開き直してください（ペイン内で q を入力してから、再度 mmap_open を実行します）。

pi は、間にマーケットプレイスを挟まず、インストールしたパッケージを更新します。

pi update npm:mellos-mapping

これは npm ソースの場合です。git ソースは、pi 自身の更新処理によって設定で指定された ref に合わせて更新されます。また、バージョン付きの指定（npm:[email protected]）は固定され、更新対象から除外されます。その後、セッションを再起動してください。セッションは自身が起動した map サーバープロセスを所有しているため、実行中のセッションは終了するまで、起動時に使用していたコピーを使い続けます。

0.19 からのアップグレード

0.20 ではストアの保存先が .claude/ から .mellos/ に移動しました。マップは特定のクライアントではなく、このツールに属するためです。サーバーとウォッチャーは起動時にそれぞれ一度だけ移動を実行し、移動した場合は stderr に次の1行だけを出力します （mellos-mapping: moved the legacy .claude map store to .mellos/ — commit the move.）：

0.19 以前	0.20 以降
.claude/mellos-mapping.json	.mellos/map.json
.claude/mellos-mapping.pages/	.mellos/pages/
.claude/mellos-mapping.config.json	.mellos/config.json

統合も上書きも行われません。.mellos/ ストア（マップ、ページ、または設定）がすでにあるプロジェクトは、従来のディレクトリに何が残っていても変更されません。マップを git で管理している場合は、移動をコミットしてください。git add -A .claude .mellos` を実行すると、削除と未追跡ファイルの集まりではなく、名前変更として記録されます。

いずれかのプロセスが .claude/ に触れるのは、この移動のときだけです。その後、ツールは .mellos/ 以外には書き込みません。また、起動時に特定したプロジェクトディレクトリの外に書き込むこともありません。

ChatGPT App · Codex モード

これは ChatGPT デスクトップアプリの Codex モードです（Codex App とも呼ばれます）。 ソースブランチから次のコマンドを実行してください。chatgpt-app では、ホスト引数を省略します。このコマンドにより、デスクトップスキル、マーケットプレイス、8つの MCP ツールが設定されます。

node install.mjs chatgpt-app

新しい会話を開始します。デスクトップスキルのデフォルトは web-terminal です。 mmap_open {surface: "web-terminal", page: "<slug>"} を実行するとローカルサービスが起動し、AI がその URL を現在の会話の右側にあるブラウザーパネルで開きます。mmap ターミナルは専用のフォントサイズセレクター付きで自動的に起動するため、手動で貼り付けたり Computer Use を使ったりする必要はありません。グラフィカルな SVG、ネイティブターミナル、Markdown も引き続き利用できます。古い MCP スキーマを使用している場合は、node "<plugin root>/dist/web.mjs" "<project>" --terminal --page <slug> を実行してください。 パネルへのリクエストがキューに入っても、ユーザーがそれを見られるとは限りません。 デスクトップでのインストールと制限事項を参照してください。

Windows Terminal 内の Codex CLI（デスクトップ統合ターミナルではありません）では、node <plugin root>/scripts/open-pane.mjs <project dir> を実行します。これにより、セッションをホストしているターミナルウィンドウが分割され、キーボードフォーカスは会話に保たれます。そのウィンドウを特定またはフォーカスできない場合は、別の場所で開くことなく、失敗を報告します。--window を指定すると、別のウィンドウを明示的に選択できます。特定のページを開くには --page <slug> を追加します。すでにペインが開いている状態で --page を付けて再実行すると、このコンソールに属するペインの表示先が切り替わります。別のセッションや別ウィンドウで開いたマップは、この分割には該当しません。ペインは、書き込み中のページ、つまりエージェントが現在操作しているマップに自動追従します。f を押すと自動追従を切り替えられます（手動でページを切り替えても自動追従はオフになります）。または --no-follow を付けて起動してください。それ以外の環境では、プロジェクトディレクトリから別のターミナル（または任意のターミナル分割）で node <plugin root>/dist/watch.mjs を実行します。どちらも同じフラグを受け付けます。ペインのフラグを参照してください。

デスクトップ版 Markdown マップ

ユーザーがドキュメント表示を選ぶと、スキルは mmap_open {surface: "markdown", page: "<slug>"} を使い、返されたファイルを現在の会話の横に開きます。ドキュメントには、色付きの SVG 依存関係マップに加えて、モジュールの詳細、根拠、子ページへのリンクが埋め込まれます。ウェブサーバー、ブラウザーのレンダリングプロセス、Mermaid のサポート、追加のランタイム依存関係は必要ありません。

MCP によるマップの書き込みが成功すると、有効になっているプレビューが .mellos/previews/ で再生成されます。JSON が引き続き信頼できる唯一の情報源です。画像ノードは静的です。ファイルの表示とビューアーの自動更新は、デスクトップホスト側の機能です。再生成、キャッシュの動作、制限事項についてはデスクトップマップガイドを参照してください。

オプションのインタラクティブ Web ビューアー

追加のインタラクティブ Web ビューアーは、 mmap_open {surface: "web", page: "<slug>"} または node "<plugin root>/dist/web.mjs" "<project directory>" --page <slug> で利用できます。 返された URL をホストの右側のブラウザーパネルで開いてください。ライブ更新、 パン／ズーム、ホバーおよびピン留めした詳細、検索、依存関係の強調表示、 フィルター、グループの概要、サブマップ、テーマを利用できます。 node "<plugin root>/dist/web.mjs" "<project directory>" --stop で停止します。 Markdown／SVG とターミナルのワークフローも引き続き利用でき、すべてのサーフェスで 同じマップデータを共有します。Web ビューアーの詳細を参照してください。

あらゆる MCP クライアント

このサーバーは npm で提供されるため、あらゆる MCP クライアント（Cursor、Windsurf、Zed、 Gemini CLI、…）で、標準の stdio エントリーを使って実行できます。

npx -y mellos-mapping

マップファイルはクライアントセッションの作業ディレクトリ （.mellos/map.json）に作成されます。同じプロジェクトからライブペインを開きます。

npx -y -p mellos-mapping mellos-mapping-watch

サーバーは、次の順序でプロジェクトディレクトリを選択します。MELLOS_MAPPING_CWD （固定ディレクトリからサーバーを起動するクライアント向けの明示的な上書き）、 次に CLAUDE_PROJECT_DIR（プラグインの MCP サーバー向けに Claude Code が設定する値）、 最後にサーバープロセス自身の作業ディレクトリです。クライアントが作業中の プロジェクトとは別の場所からサーバーを起動する場合は、MELLOS_MAPPING_CWD を設定してください。

スキル／規律レイヤーは Claude Code と Codex 専用です。それ以外のクライアントでは、 8 つの mmap_* ツールとペインを利用でき、プロンプトは各自で用意します。

使い方

1. Claude に、ある程度複雑なものの構築を依頼します。同梱のスキルにより、Claude は ゴーストデザインを宣言し、作業中にマップを最新の状態に保ちます。
2. ペインは自動で開きます。書き込みのたびに、実際に誰かが見ているかどうかが Claude に 伝わります（誰が見ているかを参照）。誰も見ていない場合は、Claude が mmap_open でペインを開くか、表示先を切り替えます。自分で覚えておく必要はありません。 任意のターミナルで mmap を実行するか、会話中に /mellos-mapping:mmap を実行して、 自分で開いたり閉じたりすることもできます（Windows では Windows Terminal の分割ペイン、 tmux 内では tmux の分割ペイン、Pebrel 内では Pebrel の分割ペイン、または別のターミナルで 実行するコマンドを表示します）。Windows では、複数のウィンドウを開いていても、 ペインは自分のセッションをホストするターミナルウィンドウで開きます。マップを専用の ウィンドウで開くには --window を指定してください。フォントに罫線文字がない場合は --ascii を使用してください。
3. 下からノードが点灯する様子を確認します。全体像に不安を感じたら、作業を中断してください。 そのための機能です。

Linux と macOS では、mmap_open と mmap は tmux を自動的に使用します。ランチャーは 継承した TMUX／TMUX_PANE を対象にします。ツールプロセスでこれらの変数が失われた場合は、 デフォルトの tmux サーバー上にある、アタッチ済みの単一セッションを検出します。デフォルトでは 入力フォーカスを維持する右側の分割ペインを開きます。--window を指定すると、新しい tmux ウィンドウを作成します。繰り返し開くと、元のペインまたはセッションのウィンドウに 結び付けられたウォッチャーを再利用します。

複数のセッションがアタッチされている場合や、カスタムの tmux ソケットを使う場合は、 MCP サーバーの環境で次の変数を設定してください（変更後はサーバーを再起動してください）。

変数	意味
MELLOS_MAPPING_TMUX_TARGET	work:2.1 や %7 など、明示的な tmux セッションまたはペイン
MELLOS_MAPPING_TMUX_SOCKET	/tmp/my-tmux/socket など、ソケットの絶対パス

Pebrel 内では、mmap_open と mmap は Pebrel のランタイム CLI（PEBREL_CLI）を使って、会話をホストするペインを分割します。 ランチャーはプロセスツリーから、そのペインがどのウィンドウにあるかを確認し、会話に 入力フォーカスを戻して、ウォッチャーを新しいペインのシェル（PowerShell、cmd、または POSIX シェル）に入力します。ウォッチャーの終了時にシェルも終了するため、マップとともに ペインが閉じます。--window を指定すると、新しい Pebrel ウィンドウが開きます。tmux 内では、 分割ペインの操作は tmux が担います。 セッションが曖昧な場合、デタッチされたセッションの場合、または tmux が見つからない場合は、具体的なエラーと、プロジェクトと指定されたページを含む完全に引用符で囲まれたウォッチャーコマンドが表示され、見えるターミナルに貼り付けられます。マップへの書き込みは引き続き利用できます。オープンに失敗した後、アシスタントは環境が変わった場合、または要求された場合にのみ再試行します。

ペインはマウス操作に対応しています（xterm SGR の全イベントトラッキング — htop と tmux が使うものと同じプロトコルです）。

入力	操作
ノードにカーソルを合わせる	そのノードのワイヤーを強調表示し、マップの下に詳細をプレビューします
ノードをクリック	ノードを固定します — マウスが離れても詳細が表示され続けます
空白部分をクリック／Esc	固定を解除します。何も固定されていない場合、Esc でダイブから戻ります
ホイール／+ -	フォーカス中のノードを基準にズームします（下の段階を参照）
左ドラッグ	マップがペインより大きい場合、つかんでパンします
Shift+ホイール	垂直にスクロールします
ホイールの傾き（水平）	横方向にパンします
hjkl／矢印キー	表示位置を少し動かします
Tab／Shift+Tab／1-9／タブをクリック	ページ（並行するマップ）を切り替えます
タブ行でホイール操作／‹ › をクリック	ページを切り替えずに、あふれたタブ列を移動します
f	自動追従を切り替えます（ページを参照）
x、またはアクティブなタブの × をクリック	表示中のページの削除を確認します。ウィンドウ内でもう一度押すと、そのファイルが削除されます（ページを参照）
⊞ ノードをダブルクリック	そのサブマップ（子ページ）にダイブします
Backspace／Esc	最後のダイブから戻ります
⋯ の区切りをドラッグ	詳細パネルのサイズを変更します — 上に引き上げると、長い設計ノートをすべて読めます
0	パンとズームをリセットします
q／Ctrl+C	ペインを終了します

それ以外のキーは意図的に何も起こしません。ペインが認識しないエスケープシーケンス（ファンクションキー、Home／End、PgUp／PgDn、Insert／Delete、修飾キー付き矢印キー）は、ペイロードのバイト列がホットキーとして読み取られることなく、シーケンス全体が消費され、何も起こりません。

ズームでは、まず図を拡大縮小し、段階の端でのみ表示モードを切り替えるため、どのレベルでも意味のあるデータが表示されます。

detail+ ← detail ← 100% ← 85% ← 70% ← 55% ← overview

• 100%を超えて拡大 — detail では、ボックス内に根拠と設計ノートの最初の3行が展開表示されます。detail+ では、最大12行のノートを表示できる読書カードへと幅が広がります。
• 85～55% — 余白が詰まり、ラベルは縮尺に応じて省略されますが、ボックスはボックスのままです。
• 55%未満 — ラベルが意味をなさなくなるため、マップは集約表示になります。宣言された各グループ（バンド内のラベル付きサブシステム）が、foundation subsystem 1/2 という名前の1つのボックスになり、ステータスはメンバーから算出されます。エッジはグループに集約され、グループに属さないノードはそのまま表示されます。実際の地図と同じように、ズームアウトすると匿名の点ではなく、地方名が表示されます。（グループがないマップでは、バンドごとの数を含むグリフのみの配置に切り替わります。） フッターには常に現在のレベルが表示されます。

マップの下、マップとヒント行の間には、高さが固定された詳細パネルがあります。ドラッグできる区切り線、ステータスに応じた色のヘッダー、フォーカス中のノードの根拠、両方向のワイヤー（uses → … · used by ← …。各隣接ノードにはそれぞれステータスのグリフが付きます）、そして折り返し表示される設計ノートが表示されます。フォーカス中の項目がない場合は、代わりにマップのダッシュボードが表示されます。高さは固定されているため、詳細がマップに重なることはなく、レイアウトが跳ねることもありません。

グリフ

マップが描画される場所ならどこでも、ステータスごとにグリフは1つです。ペインのボックス、タブストリップ、詳細パネル、そして同じストアを読み取るその他のクライアントで共通です。

Unicode	ASCII	意味
·	.	計画済み — 宣言済みで、未着手
⠿	*	進行中、待機中 — アニメーション表示が可能なボックスでは、代わりに点字フレーム（⠋⠙⠹…）を回転させるか、ASCII では4本バーのサイクルを表示します
■	#	完了、エビデンスあり
□	o	完了、エビデンスの記録なし — 同じ主張ですが、裏付けはありません
✗	X	リグレッション：完了していましたが、現在は壊れています
⊞	+	バッジ：ノードがサブマップにリンクしており、ダブルクリックで中に入ります

図の下の凡例には4つのステータスが記載されます。□ エビデンスなしで完了は、実際にそれを含むマップにのみ追加されます。4つは語彙であり、これはここで今、破られているルールです。ドキュメントの図の種類では、ステータスの凡例がノード種別のグリフに置き換わります。

ペインのフラグ

ペインの起動スクリプト（scripts/open-pane.mjs <project dir>）とウォッチャー（dist/watch.mjs）は、同じウォッチャーフラグを受け取ります。起動スクリプトはフラグをそのまま渡し、認識できないフラグは無視せずに拒否します。

フラグ	効果
--page <slug>	このページを開きます。このコンソールのペインがすでに実行中の場合は、別のペインを開かずに表示先を切り替えます
--ascii	罫線グリフのないフォント向けの、純粋な ASCII 文字セットを使用します
--no-color	ANSI カラーを使用しません
--no-mouse	ターミナルマルチプレクサがマウスを独占的に使う場合に、マウスレポートを無効にします
--no-follow	自動追従をオフにして起動します
--interval <ms>	ポーリング間隔。デフォルトは250、最小値は50です

起動スクリプト専用：--windowは、セッションのウィンドウを分割する代わりに、専用の「mellos-mapping」ウィンドウを開きます。--forceは、このプロジェクトですでにペインが実行中でも、別のペインを開きます。ウォッチャー専用：--file <path>は、デフォルトページの状態ファイルを指定します（起動スクリプトはプロジェクトディレクトリからこれを導出します）。

ペインの所有権は、内部ウォッチャーフラグ--owner <token>と、ビューアーレポートの任意フィールドownerで管理されます。起動スクリプトは、ソースコンソールのプロセスとその作成時刻からトークンを導出します。手動で起動するウォッチャーでは省略できます。バインドされたビューアーへのフォーカス要求と終了要求にはその PID が使われるため、同じプロジェクトの別のウィンドウが要求を受け取ることはありません。引数なしのmmapは、現在のコンソールにバインドされたペインのみを切り替えます。mmap --windowは、プロジェクト専用の別ウィンドウを切り替えます。

mmap コマンド

どのターミナルでも mmap と入力すると、切り替えが行われます。現在のディレクトリが属するプロジェクトのマップペインを開くか、すでに開いているペインを閉じます。

入力	動作
mmap	このプロジェクトを監視しているものがない場合はペインを開き、監視中のものがある場合は閉じます
mmap <page-slug>	指定したページで開くか、すでに開いているペインの表示先をそのページに切り替えます。閉じることはありません
mmap --window	現在のウィンドウを分割する代わりに、専用の「mellos-mapping」ウィンドウで開きます
mmap --force	すでにペインが動作していても、別のペインを開きます

プロジェクトは、git がルートを見つけるのと同じ方法で、現在のディレクトリから上位へたどり、.mellos/ ストアがある最も近いディレクトリを探します。まだマップがないプロジェクトにいても問題ありません。ペインは待機画面で開き、最初の mmap_declare が実行されるまでその状態を表示します。

閉じる処理はシグナルではなく、ストアを介して行います。mmap はマップの隣に一度だけ使われるリクエストを書き込み、ペインは次のポーリング時（デフォルトでは 250 ms）にそれを読み取って終了します。これにより、ターミナルは元の状態どおりに戻ります。マウスレポートはオフになり、カーソルは表示されます。待機画面にあるペインも同じ方法で閉じます。リクエストは読み取られると削除され、ペインが異常終了した際の残骸は次回の起動時に一掃されるため、古いリクエストが新しいペインを閉じることはありません。

上記のウォッチャーフラグはすべてここでも使え、そのまま転送されます。不明なフラグは黙って無視されず、使用方法のエラーになります。npm パッケージを使っていない場合は、mmap を一度インストールする必要があります。Claude Code の会話内では、/mellos-mapping:mmap で同じペインを開けます。

ページ

プロジェクトでは、複数のマップを並べて管理できます。1 つの作業につき 1 ページです。Claude は任意の mmap_* ツールに page を渡してページを指定します。2 つ目のページができると、ペインにタブバーが表示されます。アクティブなタブは、そのマップ全体のステータスカラーで太字表示されます。各ページは、それぞれ独自のパン、ズーム、ピン留めしたノードを記憶します。

デフォルトでは、ペインは書き込み中のページ、つまりエージェントが現在操作しているマップに追従します。そのため、宣言や更新が行われると、閲覧者も自動的にそのページへ移動します。f でこの動作を切り替えられます。手動でページを切り替えると追従はオフになり、--no-follow を指定すると追従オフの状態で起動します。追従がオフの場合、バックグラウンドのページに変更があると、そのページのタブがステータスカラーで点灯しますが、表示中のページが勝手に切り替わることはありません。明示的に指定した --page は追従より優先され、まだ存在しないページをリクエストした場合は、そのページが作成された時点で表示されます。

ページを削除する。 作業が終わっても、そのページを残しておく必要はありません。ペインで x を押すと、マウスがアクティブなタブ上にある場合はそのタブに表示される × を押した場合も、削除の確認が求められます。フッターに press x again to delete <page> と表示され、3 秒以内にもう一度押すと、そのページのファイルが削除されます。ページを切り替えるか、Esc を押すか、何もしないまま待つと、削除リクエストは取り消されます。× はアクティブなタブにのみ表示されるため、非アクティブなタブをクリックすると、まずそのタブに切り替わり、次のフレームで × が表示されます。ツール呼び出しから削除する場合は mmap_remove {pages: ["slug", …]} を使い、呼び出しで行われたマップの編集の後に適用されます。どちらの場合も、ファイルは完全に削除されます。マップはプレーンな JSON なので、元に戻すにはコミット済みのものを使うしかありません。

状態は、プロジェクトルートにあるツール管理の .mellos/ ディレクトリに保存されます。

パス	内容
.mellos/map.json	デフォルトページです。任意であり、名前付きページで作業するプロジェクトにはありません
.mellos/pages/<slug>.json	名前付きページごとに1つのファイル
.mellos/config.json	プロジェクトのマッピングポリシーです（セットアップを参照）
.mellos/focus	ランチャーから実行中のペインへの、一度限りの「このページを表示」リクエストです。ペインがポーリングの1回分の間にこれを読み取り、削除します
.mellos/quit	mmap トグルからの、一度限りの「自分を閉じる」リクエストです。同じ方法で読み取り、削除されます
.mellos/viewers/<pid>.json	実行中のペインごとに1つのレポートです。表示中のページと自動追従が有効かどうかを示し、実行中は1秒ごとに更新されます（閲覧者を参照）
<any of the above>.<pid>.<random>.tmp	保存処理中のファイルです。対象ファイルに名前を変更して置き換えるか、削除されます。残っている場合は、書き込みに失敗して（その旨が報告され）、クリーンアップも実行できなかったことを意味します
.mellos/.write-lock	OS プロジェクトロック用の永続的な通常ファイルです。追跡対象から外し、通常の操作中は削除、名前変更、置き換えをしないでください

マップファイルは通常の JSON なので、マップの履歴を Git に残したい場合は安全にコミットできます。focus、quit、viewers/、.write-lock は Git の対象から外してください。最初の3つは実行時メッセージを保持します。ロックファイルは、どのプロセスもロックを保持していないときも、その場所に置いたままにする必要があります。

並行処理について、簡潔に説明します。 保存はすべてアトミックです。専用の一時ファイルに書き込み、対象ファイルに名前を変更して置き換えるため、ストアをポーリングする読み取り側が見るのは、以前の完全なマップか新しいマップのどちらかであり、途中まで書き込まれた状態ではありません。すべてのグラフ書き込み側（MCP、HTTP ビューアー、ウォッチャー）は、プロジェクト単位で同じノンブロッキングの OS 排他ロックを使います。ロックは、置き換え対象のマップファイルとは別の専用固定ファイルに保持され、処理の完了時またはプロセス終了時に OS がロックを解放した後も、その場所に残ります。競合が発生すると、再試行可能な BUSY が返されます。

ロックにより、各操作の読み取り、変更、保存が直列化されます。以前の読み取りに基づいて計算された編集を保護するには、expectedRevision を渡してください。これはロック内で比較され、リビジョンが古い場合は CONFLICT が返されます。指定しない場合、後続の書き込みによって同じフィールドや、context などの値全体が上書きされる可能性があります。ページを分けることで無関係な作業を分離できますが、同じページを共有する場合は、リビジョンを確認した編集が引き続き必要です。低レベルの saveMapFile、手動編集、古いプロセスはこの契約の対象外です。アップグレードする前に、プロジェクトの古い MCP、ビューアー、ウォッチャーのプロセスをすべて停止してください。古いロックディレクトリには、一度限りの移行が必要です。境界とアップグレード手順については、永続マップ API ガイドとプロジェクトのロックを参照してください。

図の種類

デフォルトの種類である dev は、前述の進捗を継続的に記録する台帳です。同じレイヤー型 DAG の仕組みでドキュメント用の図も描画できます。mmap_declare に kind を渡すと、そのページは中立的なスタイルで描画されます。シンプルな塗りつぶしのボックスを使い、ゴースト、スピナー、進捗カウントは表示されません。

種類	表現	追加要素
architecture	レイヤー化されたコンポーネント（モジュールの依存関係、呼び出しグラフにも対応）	エッジにプロトコルのラベルを表示します
dataflow	パイプラインの段階をレイヤーとして配置し、ソースを下部に表示します	エッジにデータのラベルを表示します
behavior-tree	葉（アクション）を下部、ルートを上部に配置します（マインドマップ、WBSにも対応）	ノードの種類 selector sequence parallel decorator condition action はグリフとして描画されます
sequence	従来型の呼び出し／戻りです。時間は上から下へ流れ、参加者はレーンのヘッダーとして表示されます。各呼び出しと戻りは、実行する参加者のレーンにおけるイベントです	lanes は参加者を表し、エッジのラベルはメッセージを表します

ノードの種類とエッジのラベルは、dev マップでも使用できます。状態機械は意図的に対象外です。状態遷移は循環する一方、ここでのエッジは下向きにしかつながらないためです。

サブマップ

ノードは submap: <page-slug> を指定して子ページにリンクできます。ペインには ⊞ バッジが表示され、ダブルクリックすると子マップに入り、Backspace で戻ります。 ページだけで構成されたマップのマップです。新たなストレージも、不変条件も必要ありません。 ノードがサブマップにふさわしいかどうかは AI の判断に委ねられます。ほとんどの場合は該当しません。

サブマップは兄弟ではなく、内部の詳細です。つまり、別のページから入るページがタブに表示されることはありません。タブバーが消えてしまわないよう、2 つの工夫をしています。ノード自身が自分のページを指定しているページは、ほかのページを非表示にしません。また、リンクの循環は、循環の外部にあるページから中に入らない限り、タブを維持します。循環には戻るための外部が存在しないためです。サブマップに入ると、タブ行はパンくずリスト ⌫ parent map ▸ node に変わり、これをクリックするか Backspace を押すと戻れます。非表示のサブマップがバックグラウンドで変更されると、フッターに通知が表示されます。

MCP ツール

既存のページを再開するには、まず mmap_read を使用してください。新しい会話は新しい作業の開始を意味しません。安定した ID、フィルター付き読み取り、リビジョンを確認した書き込みを使用してください。永続マップ API ガイドでは、完全な CRUD、アトミックな混合バッチ、コンテキストのチェックポイント、ソースハッシュ、作業ツリーの境界について説明しています。

ツール	目的
mmap_declare	マップを拡張します。タイトル（null で削除）、図の種類、レイヤー帯、レーン、グループ（サブシステム）、ノード（status、evidence、detail、kind、group、lane、submap を指定）、エッジ（必要に応じてラベルを指定）を追加します（バッチは全件成功か全件失敗）
mmap_update	進捗を記録し、改訂します。ステータス（planned → in-progress → done +証拠、regressed）、ノードのラベル変更、別の帯への移動（layer）、グループまたはレーンへの参加・離脱、ノードの種類または submap の設定、帯（layers）の名前変更と順位変更、グループ（groups）とレーン（lanes）のラベル変更を行います。消去可能なフィールドは null で消去できます
mmap_remove	改訂します。エッジ、ノード、グループ、レーン、空の帯を削除します。また、pages を指定すると、ページ全体、ファイル、すべてを削除します（永久削除。現在の呼び出しによるマップの編集後に適用）
mmap_view	現在のマップをテキストとしてインラインでレンダリングします（任意の zoom、-4～2）。末尾の pages: 行には、プロジェクト内のすべてのページと現在表示しているページが示されます
mmap_read	ページの構造化された検索、正確な ID、フィルター／ページネーション付きの読み取り、コンテキストとソースの変更
mmap_batch	リビジョン確認付きで、1 ページに対する作成・更新・削除を組み合わせたトランザクションを実行します
mmap_setup	プロジェクトのマッピングポリシー（マップを開くタイミング）を取得・設定します
mmap_open	マップを画面に表示します。ペインを開くか、開いているペインの表示先を page に切り替えます（専用ウィンドウの場合は window: true）。コマンドを実行したかどうかだけでなく、その後ペインから実際に応答があったかどうかを返します。また、ペインを閉じることはありません

バッチは、帯 → グループ → レーン → ノード更新の順に適用されます。また、1 つのノード更新では、他のフィールドより先に layer でノードを移動するため、1 つの項目でノードを移動し、新しい帯のグループに参加させることができます。

台帳に意図しない内容が記録されないよう、境界では次の内容を拒否します。

• 不明なキー。キー名を明示します。evidance のようなスペルミスは、どの階層でもフィールドが黙って破棄されるのではなく、エラーになります。
• テキストフィールド内の制御文字。ラベルに ESC シーケンスを保存すると、マップを開くすべての人のターミナルが再描画されるおそれがあります。例外は detail です。メモの記述には改行とタブを使用できますが、それ以外（ESC、BEL、単独の CR）は引き続き拒否されます。ファイルの読み込みとライブラリの保存にも、同じ制御文字のルールが適用され、古いファイルの複数行の証拠は保持されます。ターミナルでのレンダリングでも、ライブラリの呼び出し元が直接作成したマップ内の制御文字は無害化されます。
• フィールドが任意の場合の空文字列。フィールドを消去するには null を使用します。実際の項目と見分けがつかない空欄を表示する空白文字列は使用しません。
• submap が呼び出し自体の対象ページを指すノード。これは親ページへのリンクではなく、終点のないリンクです。
• 同じ呼び出しの対象ページ、またはプロジェクトに存在しないスラッグを対象とするページ削除。1 回の呼び出しで、削除対象のマップを編集することはできません。また、どのページにも一致しない名前は、競合よりも入力ミスである可能性がはるかに高いため、拒否時には実在するページが一覧表示されます。

書き込みが反映されなかった場合は、save failed, nothing changed (retry) と応答します。以前のファイルはそのまま保持され、もう一度呼び出せば復旧できます。

誰が見ているのか

画面に表示されていないマップはマップではなく、ただのファイルです。そして、これまではシステム内のどの機能もその違いを判別できませんでした。アシスタントが設計を宣言し、ノードを組み立てながら点灯させ、そのすべてを、あなたが一度もペインを開いたことのないストアに報告していました。

現在は、各ペインが実行中に簡単なレポートを公開します。.mellos/viewers/ にペインごとに1つファイルが作成され、1秒ごとに更新されます。そして、書き込みも表示も、そのたびにレポートの内容が示されます。

項目	意味
pane: CLOSED	このマップを見ている人はいません。アシスタントはあなたに開くよう頼む代わりに、mmap_open でペインを開きます
pane: running on this page	実行中のプロセスがこのページを報告しています。ターミナルは非表示の場合があります
pane: open on <other>, auto-follow on	ペインは最後に書き込まれたページを追従するため、自動的にここへ切り替わります
pane: open on <other>, auto-follow OFF	あなたが手動でそのページに固定しました。変更は実際に行われていますが、画面には表示されていません。アシスタントには、表示を切り替えるのではなく、その旨を伝えるよう指示されます

同じレポートは、mmap とランチャーの「ペインはすでに開いているか」という問いにも答えます。以前はこの確認に Windows 専用のプロセススキャンが必要で、画面にどのページが表示されているかは分かりませんでした。ペインのレポート更新が止まると、5秒後にそのレポートは無視され、1分後に削除されます。そのため、強制終了されたペインが見ている人がいると主張し続けることはありません。

ハートビートだけでは、画面に表示されていることを確認できません。明示的に tmux で開くと、既存のウォッチャーのウィンドウも選択され、別のペインがズームされていればその状態が解除されます。また、表示中と報告する前に、接続されたセッションのアクティブなウィンドウを確認します。TMUX のないシェルからそのウォッチャーにフォーカスすると、元の所有者が再利用されます。

セットアップ：マップを開くタイミングを選ぶ

マッピングをどれほど積極的に行うかは、リポジトリの性質ではなく、習慣によるものです。そのため、インストール後の最初のセッションで、あなたのために一度だけ選択します。

• always — ワークフロー、設計、アーキテクチャ、技術的な依存関係など、構造化されたタスクをすべてマップします。アシスタントが自分からペインを開きます。記録された回答が常時の同意として扱われるため、確認を求めなくなります。
• complex — 同様にマップしますが、中規模または複雑なタスクに限ります。複数のモジュール、新しいサブシステム、およそ1時間以上かかる作業などが対象です。
• on-request — 明示的に依頼した場合にのみマップします。マップのないプロジェクトでは、プラグインは何も発言しません。ノイズをゼロにすることが目的です。

回答は <your home>/.mellos/config.json に保存され、プラグインの SessionStart フックを通じてすべてのセッションに反映されます。このフックが回答を読み取り、あなたが何か入力する前に、該当する指示をアシスタントに渡します。プロジェクトごとのセットアップは、今後一切必要ありません。

プロジェクトごとに異なる設定にすることもできます。mmap_setup {policy, scope: "project"} を実行すると、そのプロジェクトの .mellos/config.json にポリシーが保存され、プロジェクトのポリシーがユーザーのポリシーより優先されます。考えが変わったときは、いつでも /mmap setup を実行して、どちらのスコープでも質問をやり直せます。ポリシーはアシスタントの動作を案内するもので、ツールを制限するものではありません。どのポリシーでも、明示的にマップを依頼すれば常に実行できます。

フックのないホスト（Codex CLI、MCP クライアント単体）では、別の方法で質問します。どちらのスコープにもポリシーが存在しない間は、mmap_declare の応答ごとに、アシスタントへあなたに尋ねるよう伝えるメモが含まれます。そのメモは、どこかで一度回答した時点で、すべてのプロジェクトにおいて表示されなくなります。

ツールによって適用される構造上の不変条件：レイヤーはランク（0..99の整数。0が最下位で、マップ内で一意）に従って全順序を形成します。各ノードはちょうど1つのレイヤーに属します。エッジは厳密に下方向を指します。これにより、グラフは構造上、非循環になります。ノードは同じレイヤーの兄弟ノードに依存できません（A が兄弟の B を必要とする場合、B は実際にはより下位の概念であるか、A と B が1つのノードである必要があります）。グループは1つの帯域内のノードをまとめます。また、ノード ID とグループ ID は単一の名前空間を共有します。1つの ID が指すのはノードかグループのどちらか一方であり、両方ではありません。どちらもボックスとして描画されるため、1つの ID は1つのボックスを意味する必要があります。

開発

貢献ガイドと、 プロジェクト構成、ブランチ、復旧ガイドを参照してください。

npm ci
npm run verify

開発には Node.js 22.12 以降を使用してください。verify は typecheck、test、build （dist/ をバンドルし、宣言ファイル付きで lib/ を出力）、check:package、 check:codex、check:release を実行します。これらは npm のエントリーポイント、Codex パッケージ、インストール可能な 2 つのエディションを、それぞれの MCP ハンドシェイクも含めて検証します。

リポジトリ自体も下位層から順に構成されており、各層には仕様があります。

層	コード	仕様	担当
0 ドメイン	src/domain/	ops.test.ts	マップの値、構造上の不変条件、純粋な操作
1 フォーマット	src/store/format.ts	store.test.ts	状態ファイルの形式：リプレイ検証付きの解析、シリアライズ — I/O なし
1 ストア	src/store/store.ts	store.test.ts、atomic-save.test.ts	Node 上での状態ファイルのアトミックな永続化
1 セマンティクス	src/semantics/	semantics.test.ts	媒体に依存しないビューのセマンティクス：ズーム段階、グループ集約、ページセットのルール、シーケンスの反転、共有グリフ語彙
2 適用	src/server/apply.ts	apply.test.ts	ツールの入力 → トランザクション形式の操作シーケンス
3 サーバー	src/server/server.ts	server.test.ts、save-failure.test.ts	stdio 経由の 8 つの MCP ツール
4 描画	src/render/	render.test.ts、routing.test.ts	ASCII レンダラーとそのワイヤールーティング
4 ペイン	src/watch/	watch.test.ts、pane-state.test.ts、input.test.ts	ポーリングペイン：ページセット、入力解析、パネルとクローム
— ランチャー	scripts/	open-pane.test.mjs、codex-register.test.mjs	Node 単体で実行するエントリーポイント
— パッケージング	package.json	tests/lockfile.test.ts、browser-safe.test.ts	配布するものと配布先

dist/ は意図的にコミットされています。プラグインのインストールではこのリポジトリをクローンして何も実行しないため、エントリーポイントはバンドル済みで配布されます。CI はコミット済みの dist/ と新規ビルドとの差分を確認するため、ソースを変更しても再ビルドを忘れると失敗します。

ライブラリ

下位層はライブラリとしても利用できます（npm run build は型宣言付きで lib/ を出力し、npm パッケージに含めます）。サブパスのエクスポートはソース構成に対応しています。

サブパス	内容	ブラウザー対応
mellos-mapping/domain/types	マップの値、ID、ランク、ステータス、エラー	はい
mellos-mapping/domain/ops	マップに対する純粋な操作	はい
mellos-mapping/format	状態ファイルの解析／シリアライズ、ページ ID	はい
mellos-mapping/semantics	ズーム段階、グループ集約、フォーカスとページセットのルール、共有グリフ語彙	はい
mellos-mapping/render	ターミナルレンダラー	同じ方法で制限付き（純粋な処理ですが、出力は文字セルのため、ターミナルホスト向け）
mellos-mapping/store	ファイルシステムへの永続化、アトミックな保存、フォーカスファイル、ポリシー	Node のみ
mellos-mapping/server	バンドル済み MCP サーバーのエントリーポイント — 起動対象であり、インポートするモジュールではありません	Node のみ

ブラウザー対応とは、インポートの依存関係全体で Node の組み込みモジュールを一切使用しないことを意味します。これはテストで検証されます。これにより、グラフィカルクライアント（Web パネルやエディタービュー）は状態ファイルを解析し、ターミナルペインの描画に使われる集約、ズーム、グリフのセマンティクスをそのまま再利用できます。

オプションの GitHub スターリマインダー

npm/npx でインストールした場合、7 日以上が経過し、異なる 3 つの UTC 日付にマップの表示に成功すると、閉じることのできる小さなリマインダーが 1 回表示されることがあります。Web ビューアーではフォーカスを奪わずにインラインで表示されます。ネイティブの対話型ターミナルでは、表示セッションが正常に終了した後にのみ表示されます。MCP の返信、AI プロンプト、インストールログ、CI、パイプ出力に追加されることはありません。プラグイン版とソースコードのチェックアウトは対象外です。

このリマインダーは、プロジェクト、バージョン、インストールをまたいで、ユーザーごとに一度だけ表示されます。スターのボタンを押すと、システムのデフォルトブラウザーで GitHub が開き、既存のサインインセッションが維持されます。起動に失敗した場合、通知は開いたままになり、アドレスをコピーするオプションが表示されます。通知を閉じる、スターのリンクを開く、または単にセッションを終了すると、再び表示されることはありません。表示前に抑止するには、ビューアー/MCP プロセスの環境に MELLOS_MAPPING_NO_STAR=1 を設定してください。初回利用時刻、最後の UTC 日付、上限付きの日数カウント、一度限りのフラグのみが ~/.mellos/support/star-reminder.json に保存されます。データがアップロードされることはなく、ユーザーがリンクを開いた場合にのみ GitHub にアクセスします。設定を読み取れない場合やストアが使用中の場合、リマインダーは通知なしでスキップされます。

コミュニティ

このプロジェクトは、LINUX DO コミュニティに参加し、支持しています。

ライセンス

MIT