mulmoterminal 4.24.0 → 4.26.0

package/README.ja.md

@@ -0,0 +1,191 @@
+# MulmoTerminal
+
+[English](README.md) · **日本語** · [简体中文](README.zh.md)
+
+**コーディングエージェントのセッションを並列で走らせ、どれが自分を待っているかを見る。**
+
+**並列 AI コーディングエージェントのためのブラウザ端末**です。複数のセッションが
+一つずつセルに入って並び、**あなたを待っているものだけが色で示されます**。
+既定は **Claude Code** で、ほかに6つの CLI を同格で扱えます —
+Codex、Antigravity、Grok、Muse、GitHub Copilot CLI、Cursor CLI。
+エージェント1体の vibe coding にシェル以外は要りません。これは**複数走らせて、どれが待っているか
+分からなくなったとき**のための道具です。セッションはリロードを越えて残り（tmux）、作業は
+**git worktree** で隔離され、ターンが終わると**スマホに通知**が飛びます。
+
+**すべてのセルが本物の pty です。** `htop`、`lazygit`、開発サーバー、Claude Code —
+ここでは同じ種類のものです。だから「worktree あたり1セッション」の制限は**エージェントにだけ**
+掛かり、シェルや `yarn dev` はエージェントが作業している worktree に同居できます。
+
+## デモ
+
+![MulmoTerminal — 状態ごとに色分けされた Claude Code セッションのグリッドがリアルタイムに更新される様子](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/hero.gif)
+
+*グリッドの実機。各セルが **作業中** / **完了** / **あなた待ち** で色分けされます。*
+
+```bash
+npx mulmoterminal@latest        # http://localhost:34567 で起動し、ブラウザが開きます
+```
+
+**Node 22.12 以上**と、`PATH` に通ってログイン済みの
+[`claude`](https://claude.com/claude-code) CLI が必要です。
+`npx mulmoterminal@latest init` が、足りないものを教えてくれます。
+
+### tmux + iTerm のペインで十分では？
+
+並列に走らせること自体は難しくありません。tmux で十分です。失われるのは
+**5つのうちどれが自分を待っているか**です。ペインは不透明で、作業中・完了・権限確認待ちの3つが、
+読むまで見分けられません。
+
+MulmoTerminal では、すべてのセルが自分の状態を一つのグリッドに報告します —
+作業中（青）、完了（緑）、**あなた待ち**（琥珀）。画面外のセルが琥珀になれば音が鳴ります。
+さらに**1セッション1行の cockpit roster** があるので、1つに答えている間も残り4つを見失いません。
+
+tmux が入っていればその**上で**動き、[再起動を越えて残ります](#セッションの永続化-tmux)。
+
+## なぜ欲しくなるか
+
+- **全エージェントを一度に見る。** 状態で色分けされたセルのグリッド — 作業中（青）、
+  **権限待ち / あなた待ち**（琥珀）、**完了・未確認**（青）、待機。注意音とツールバーの件数表示が
+  付くので、画面外で詰まったエージェントを見落としません。1つの端末に張り付くのをやめて、
+  10体を監督する側に回れます。1つを拡大しても **cockpit roster** が残りを視界に保ちます —
+  1セッション1行で、AI 要約・直近のプロンプト・最新の返答・ブランチの **PR 状態**
+  （draft / CI 失敗 / ready / merged）が並びます。
+- **端末だけでなく、エージェントのための GUI。** 端末の横の **Canvas** パネルが、
+  エージェントが MCP 経由で出したもの — **文書・フォーム・グラフ・生成画像・HTML・
+  コレクションカード** — をそれぞれ専用プラグインで描画します。
+  エージェントはテキストを流すのではなく、インターフェースを手渡してきます。
+- **どこにいても呼び戻される。** 完了時・入力待ち時に**スマホへ Web Push** が飛び、
+  **RemoteHost** を使えばスマホから状況を見て、タップで（**yes / no / continue**）
+  答えられます。席を立ち、呼ばれ、戻る。
+- **再起動で何も失わない。** `tmux` があれば、サーバーのクラッシュ・再起動・`node --watch` の
+  リロードを越えて全セッションが生き残ります。ターン途中のエージェント、長いビルド、
+  開発サーバーがそのまま走り続け、戻ると再接続されます。
+- **グリッドから出ずに出荷する。** 各リポジトリのセルに **git ブランチのチップ**が出て、
+  ワンクリックで **git worktree** に隔離し、**diff** パネルを開き、
+  **commit / push / PR 作成**まで行えます。複数のエージェントが同じリポジトリを、
+  衝突せずに触れます。
+- **いくら掛かっているか分かる。** セッションごとの**コンテキスト %**・**トークン**・
+  **推定 $**、ツール呼び出しの**タイムライン**、セル名とコマンド出力の **AI 要約** —
+  並列エージェントの壁が、読めるものに保たれます。
+- **自分のものにする。** ディレクトリごとの**テーマ・色・名前バッジ**（`prod` は赤、
+  `staging` は琥珀）、設定可能なヘッダー、独自の注意音、そしてプロジェクトのスクリプト・
+  `.claude/skills`・デッキをセル内から起動する Run / Skill / Mulmo メニュー。
+
+![MulmoTerminal のグリッド — 4つの Claude セッションが、それぞれ色分けされたプロジェクトで並列に動いている](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/grid-2x2-live.png)
+
+*グリッドは**並列エージェントの管制塔**です。各セルのヘッダーに、切り分けに必要なものが並びます —
+**モデル・コンテキスト %**、**トークン数**（`⇡in ⇣out`）、**git ブランチ / 変更**のチップ、
+そしてエージェントが何をしているかの AI 要約。**セルの枠の色が状態を示し**、画面外で詰まったセルは
+音で呼び戻します。多数を監督し、呼ばれたところにだけ入る。*
+
+### 中身の仕組み
+
+各セッションはサーバー上で本物の PTY として動き（エージェント CLI を疑似端末に入れています）、
+WebSocket 経由でブラウザの [xterm.js](https://xtermjs.org/) 端末に流れます。
+
+**cockpit roster** は全セッションを一覧し、**作業中**（考えている）・**あなた待ち**
+（権限確認や質問 — 琥珀の点。答えるまで何も進みません）・**完了していて未確認**（緑の点）を
+リアルタイムに反映します。これは**サーバーが起動時に注入する Claude / Codex の activity hook**
+から取っており、画面の文字を解析しているのではありません。
+
+> ここが要点です。端末の中では「権限確認で止まっている」と「まだ考えている」が**同じに見えます** —
+> どちらも出力が止まるだけだからです。画面を読んでも区別できませんが、hook なら区別できます。
+>
+> （Codex は「入力待ち」を報告しません。確認ダイアログが自身の TUI に描かれ、rollout ファイルに
+> 届かないためです。したがって Codex は「作業中 / 完了」の2状態になります。）
+
+## 使ってみた人が言うこと
+
+> IDE や分割端末から移ってきた人の報告であって、ベンチマークでも、こちらが測定した主張でも
+> ありません。環境によって違うはずです。
+
+**「メモリを食わなくなった」** — エージェントを分けるために IDE のウィンドウを複数開くのは
+高くつきます。それぞれがエディタ・言語サーバー・拡張・ファイル監視を連れてくるためです。
+**64GB のマシンがその負荷で引っかかっていた**人が、移行後は滑らかに動いたと報告しています。
+ここではエージェントはサーバー上の PTY で、UI はブラウザのタブです。
+
+**「別のエージェントに返事をしなくなった」** — スクロールするテキストのペインが6つ並ぶと、
+どれも同じに見えます。**別のエージェントの端末に返事を打ち込んでいた**、最初に何を頼んだか
+分からなくなった、という報告があります。問題は注意力ではなく、**同じペインが N 個あると
+N 個の文脈を頭に保持しなければならない**ことです。状態の色分け・名前バッジ・
+ディレクトリごとの色が、それを頭から画面に移します。
+
+**「多数を見ることと1つを読むことが、二者択一でなくなった」** — 端末を6分割すると、
+どのペインも長い返答を読むには小さすぎます（4,000文字の返答でまさにそうなった、という報告）。
+エージェントを増やすたびに、読みやすさを静かに諦めることになります。
+**グリッド ↔ 拡大**がそれを解消します。全部を見て、1つを拡大してきちんと読む。
+その間も cockpit roster が残りをテキストで視界に保ちます。
+
+**「今までのセッションがそのまま来た」** — セッションはそのまま再開します（同じ
+`claude --resume`、同じ履歴）。既に作業しているディレクトリを指定すれば、履歴はそこにあります。
+移行も、やり直しも要りません。
+
+**10体いなくても元は取れます。** 並列 **1〜3** セッションの時点で移行する価値があったという
+報告があります。上に挙げた利点は「もっと多く走らせること」ではなく「見失わないこと」の話です。
+
+## インストールと起動
+
+**Node 22.12 以上**と、`PATH` 上の以下の CLI が必要です。
+
+> **どれも入れたことがない場合**は、コマンドラインの経験がない前提で、macOS と Windows の
+> 両方を最初から説明したガイドがあります:
+> [はじめに — 起動するまで](https://receptron.github.io/mulmoterminal/guide/ja/getting-started.html)
+
+| | ツール | 何ができるようになるか | インストール |
+| --- | --- | --- | --- |
+| **必須** | [`claude`](https://claude.com/claude-code) | すべての Claude セッション。本アプリはその管制塔です | `npm i -g @anthropic-ai/claude-code` のあと、一度 `claude` を実行してログイン |
+| **必須** | `git` | worktree による隔離、各セルのブランチ / 未保存ドット / diff 表示、PR フッター | `brew install git` · `sudo apt install git` · Windows: [git-scm.com](https://git-scm.com/download/win) |
+| **必須** | `gh` | 横断的な **PR & Issue** ビューとワンクリック PR 作成。`gh` のログインを使うのでトークンは保存しません | [cli.github.com](https://cli.github.com) のあと `gh auth login` |
+| 任意 | `glab` | **GitLab** プロジェクトで同じこと。self-hosted も設定可 | `brew install glab` のあと `glab auth login` |
+| 推奨 | `tmux` | **セッションの永続化** — サーバー再起動を越えて端末が残ります | `brew install tmux` · `sudo apt install tmux` · Windows ネイティブ版は無し（通常の PTY にフォールバック） |
+| 任意 | `codex` | セル内での **Codex セッション** | `npm i -g @openai/codex` |
+| 任意 | `ffmpeg` | mulmo-script パネルからの動画生成 | `brew install ffmpeg` · `sudo apt install ffmpeg` |
+| 任意 | `ollama` | 完全にローカルなモデルで Claude Code を動かす | [ollama.com/download](https://ollama.com/download) |
+
+必須でない行が無くてもサーバーは起動します。その機能が使えなくなるだけで、
+ヘッダーやパネルがその旨を表示します。
+
+```bash
+npx mulmoterminal@latest           # http://localhost:34567 で起動しブラウザを開く
+# またはグローバルに入れる:
+npm install -g mulmoterminal
+mulmoterminal
+```
+
+**止め方。** 起動した端末で `Ctrl+C`。その端末が見つからなければ、ブラウザの
+**Settings → Quit MulmoTerminal**、または任意の端末から **`npx mulmoterminal@latest stop`**。
+`tmux` が入っていればエージェントのセッションは生き残り、**Settings → Sessions that survived
+a restart** から戻ってきます。
+
+**初回セットアップ（任意）。** `npx mulmoterminal@latest init` が環境を確認し、
+Claude Code の履歴からランチャーの**ディレクトリ候補**を作り、`~/.mulmoterminal/config.json`
+を書きます。**何度実行しても同じ結果**になるので、候補を更新したくなったらいつでも再実行できます。
+
+## ドキュメント
+
+**[receptron.github.io/mulmoterminal](https://receptron.github.io/mulmoterminal/)**
+
+- **ユーザーガイド:** [日本語](https://receptron.github.io/mulmoterminal/guide/ja/) —
+  グリッドの使い方・日々のワークフロー・機能一覧・設定・スマホ通知
+- **User guide:** [English](https://receptron.github.io/mulmoterminal/guide/en/)
+- **アップデート情報:** 新バージョンや新機能は X でお知らせしています —
+  日本語は [Singularity Society (@SingularitySoci)](https://x.com/SingularitySoci)、
+  英語は [@mulmocast](https://x.com/mulmocast)
+
+## 作っている人
+
+**[receptron](https://github.com/receptron)** —
+Microsoft で **Windows 95** のソフトウェアアーキテクトを務めた
+**[中島聡](https://x.com/snakajima)** と **[有本勇](https://github.com/isamu)**。
+**[GraphAI](https://github.com/receptron/graphai)** と同じ2人です。
+
+## ライセンス
+
+MIT
+
+---
+
+> **この README は、英語版の最初の約360行（製品の説明と導入）に対応しています。**
+> 設定・アーキテクチャ・スクリプト・スキル・デッキ・worktree と PR・リモートホストなどの
+> 詳細は、[英語版 README](README.md) と
+> [日本語ユーザーガイド](https://receptron.github.io/mulmoterminal/guide/ja/) を参照してください。

package/README.md

@@ -1,5 +1,7 @@
 # MulmoTerminal
 
+**English** · [日本語](README.ja.md) · [简体中文](README.zh.md)
+
 **Run multiple coding-agent sessions in parallel — and see which one needs you.**
 
 A **browser terminal** for **parallel AI coding agents**: several sessions side by side, each in
@@ -58,8 +60,10 @@ ping to your phone when a task finishes. One `npx` command, no Electron, no conf
 npx mulmoterminal@latest        # starts on http://localhost:34567 and opens your browser
 ```
 
-Requires **Node ≥ 22.12** and the [`claude`](https://claude.com/claude-code) CLI on your
-`PATH`, already logged in. `npx mulmoterminal@latest init` reports what it can't find.
+Requires **Node ≥ 22.12**, and by default the [`claude`](https://claude.com/claude-code) CLI —
+on your `PATH` or named by `CLAUDE_BIN`, already logged in. Declare a different default agent
+(`--agent codex`, or `"defaultAgent"` in `~/.mulmoterminal/config.json`) and start-up checks that
+one instead. `npx mulmoterminal@latest init` reports what it can't find.
 
 ### Why not tmux + iTerm panes?
 
@@ -255,7 +259,7 @@ more.
 
 ## Install & run
 
-Needs **Node ≥ 22.12**, plus these CLIs on your `PATH`:
+Needs **Node ≥ 22.12**, plus these CLIs — on your `PATH`, or named by the matching `<AGENT>_BIN`:
 
 > **Never installed any of this before?** The guide walks it end to end, macOS and Windows,
 > assuming no command-line experience:
@@ -264,7 +268,7 @@ Needs **Node ≥ 22.12**, plus these CLIs on your `PATH`:
 
 | | Tool | What it gives you | Install |
 | --- | --- | --- | --- |
-| **Required** | [`claude`](https://claude.com/claude-code) | every Claude session — this app is a cockpit for it | `npm i -g @anthropic-ai/claude-code`, then run `claude` once to log in |
+| **Required** *(unless you declare another)* | [`claude`](https://claude.com/claude-code) | every Claude session — this app is a cockpit for it. Start-up requires it **by default**; declare a default agent and it checks that one instead — `npx mulmoterminal --agent codex`, or `"defaultAgent": "codex"` in `~/.mulmoterminal/config.json` (#2082). `CLAUDE_BIN` is honoured, so an install off `PATH` counts | `npm i -g @anthropic-ai/claude-code`, then run `claude` once to log in |
 | **Required** | `git` | [worktree isolation](#git-worktrees--pull-requests), each cell's branch / unsaved-dot / diff readout, the PR footer | `brew install git` · `sudo apt install git` · `sudo dnf install git` · Windows: [git-scm.com](https://git-scm.com/download/win) |
 | **Required** | `gh` | the cross-repo **PRs & Issues** view and one-click PR creation — it uses your `gh` login, so no token is stored | [cli.github.com](https://cli.github.com), then `gh auth login` |
 | Optional | `glab` | the same for **GitLab** projects (#981) — gitlab.com, and a self-hosted instance you declare in `gitlabHosts` (#1332). Same arrangement: the CLI holds the credentials, this app stores no token | `brew install glab`, then `glab auth login` (self-hosted: `glab auth login --hostname gitlab.example.com`) |
@@ -276,7 +280,10 @@ Needs **Node ≥ 22.12**, plus these CLIs on your `PATH`:
 
 The server starts without any of the non-required rows; you just lose that row's feature,
 and the header/panel for it says so. `git` and `gh` are marked required because losing them
-costs whole views rather than one button. `npx mulmoterminal@latest init` (below) reports which of
+costs whole views rather than one button. `claude` is required only until you name a different
+default agent — see
+[Starting without Claude Code](https://receptron.github.io/mulmoterminal/guide/en/agents.html#default-agent)
+· [日本語](https://receptron.github.io/mulmoterminal/guide/ja/agents.html#default-agent). `npx mulmoterminal@latest init` (below) reports which of
 these it can find.
 
 ```bash
@@ -346,8 +353,8 @@ npx mulmoterminal@latest --cwd ./my-project   # work in a specific directory
 ```
 
 The published package ships the server (run via `tsx`) plus the pre-built web UI;
-`npx mulmoterminal@latest` checks for the `claude` CLI, picks a free port, starts the
-server, and opens the browser. For local development from a clone, see
+`npx mulmoterminal@latest` checks for the `claude` CLI — or for whichever agent you set as the
+default — picks a free port, starts the server, and opens the browser. For local development from a clone, see
 [Running](#running).
 
 **Won't start with `ERR_MODULE_NOT_FOUND`?** If a first `npx` run was interrupted, a half-unpacked `~/.npm/_npx/<hash>` cache can remain and a later run fails at startup — a corrupted npx cache, not a bug in the published package.
@@ -650,7 +657,10 @@ detects `tmux` on `PATH` at startup and uses it automatically when present.
 | Plugins  | GUI-protocol Vue plugins (`@mulmoclaude/*`, `@mulmochat-plugin/*`): markdown, form, image, chart, HTML, collection, accounting, mulmoscript (MulmoCast video/slides), google |
 | Tests    | Vitest + @vue/test-utils + jsdom |
 
-Requires **Node ≥ 22.12** (uses `node --env-file-if-exists`) and the `claude` CLI on `PATH`.
+Requires **Node ≥ 22.12** (uses `node --env-file-if-exists`) and, by default, the `claude` CLI —
+found on `PATH` or named by `CLAUDE_BIN`. Declaring a different default agent (`--agent codex`, or
+`"defaultAgent"` in `~/.mulmoterminal/config.json`) makes start-up check that agent instead (#2082):
+see [Starting without Claude Code](https://receptron.github.io/mulmoterminal/guide/en/agents.html#default-agent).
 
 ---
 

package/README.zh.md

@@ -0,0 +1,172 @@
+# MulmoTerminal
+
+[English](README.md) · [日本語](README.ja.md) · **简体中文**
+
+**并行跑多个编码智能体会话 —— 一眼看出哪一个在等你。**
+
+一个给**并行 AI 编码智能体**用的**浏览器终端**：多个会话并排，每个占一格，
+**在等你的那一个用颜色标出来**。默认是 **Claude Code**，另有六个 CLI 同为一等公民 ——
+Codex、Antigravity、Grok、Muse、GitHub Copilot CLI、Cursor CLI。单个智能体的 vibe coding 一个 shell 就够了，
+这个工具是给**同时跑好几个、然后分不清谁在等你**的时候用的。会话能挺过刷新（tmux），
+工作隔离在 **git worktree** 里，一轮结束时**推送到手机**。
+
+**每一格都是真实的 pty。** `htop`、`lazygit`、开发服务器、Claude Code —— 在这里是同一类东西。
+所以「每个 worktree 一个会话」的限制**只对智能体生效**，一个 shell 或 `yarn dev`
+可以和正在干活的智能体待在同一个 worktree 里。
+
+## 演示
+
+![MulmoTerminal —— 按状态着色的 Claude Code 会话网格，实时更新](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/hero.gif)
+
+*实际运行中的网格 —— 每一格标为 **在跑**、**跑完了** 或 **等你**。*
+
+```bash
+npx mulmoterminal@latest        # 在 http://localhost:34567 启动并打开浏览器
+```
+
+需要 **Node 22.12 以上**，以及 `PATH` 上已登录的
+[`claude`](https://claude.com/claude-code) CLI。
+`npx mulmoterminal@latest init` 会告诉你缺了什么。
+
+### 为什么不用 tmux + iTerm 分屏？
+
+并行地跑起来从来不是难点，tmux 就能做。丢掉的是**五个里面哪一个在等你**。
+一个 pane 是不透明的：在跑、跑完了、卡在权限确认上 —— 不读一遍就分不出来。
+
+在 MulmoTerminal 里，每一格都把自己的状态报告给同一个网格 ——
+在跑（蓝）、跑完了（绿）、**等你**（琥珀）。屏幕外的格子变琥珀时会响一声。
+还有一个**每个会话一行的 cockpit roster**，所以你在回答其中一个的时候，
+不会丢掉另外四个的位置。
+
+装了 tmux 的话它就跑在 tmux **之上**，[重启也不会丢](#会话持久化-tmux)。
+
+## 为什么你会想要它
+
+- **一眼看完所有智能体。** 按状态着色的会话网格 —— 在跑（蓝）、**被权限挡住 / 等你**（琥珀）、
+  **跑完但还没看**（蓝）、空闲。配上提示音和工具栏计数，屏幕外卡住的智能体不会溜过去。
+  不用再守着一个终端，改成监督十个。放大其中一个，**cockpit roster** 仍然让其余的留在视野里 ——
+  每个会话一行文字：AI 摘要、上一条 prompt、最新回复、以及分支的 **PR 阶段**
+  （draft / CI 失败 / ready / merged）。
+- **给智能体的 GUI，而不只是终端。** 终端旁边的 **Canvas** 面板会把智能体通过 MCP 产出的东西 ——
+  **文档、表单、图表、生成的图片、HTML、collection 卡片** —— 各自用专属插件画出来。
+  智能体不是给你打印文字，而是递给你一个界面。
+- **人在哪里都能被叫回来。** 任务完成或等待输入时会**推送到手机**，配合 **RemoteHost**
+  还能在手机上看会话、点一下就回答（**yes / no / continue**）。走开、被叫、回来。
+- **重启不丢任何东西。** 有 `tmux` 的话，服务器崩溃、重启、`node --watch` 重载，
+  每个会话都活着 —— 跑到一半的智能体、长时间的构建、开发服务器都继续跑，回来时自动接上。
+- **不离开网格就能发布。** 每个仓库格子带 **git 分支标签**，一键隔离到 **git worktree**，
+  打开 **diff** 面板，完成 **commit / push / 开 PR**。多个智能体可以在同一个仓库里互不干扰。
+- **知道花了多少钱。** 每个会话的**上下文 %**、**token**、**预估 $**，工具调用的**时间线**，
+  以及单元格标题和命令输出的 **AI 摘要** —— 让一整墙的并行智能体保持可读。
+- **按你的习惯来。** 按目录设置**主题、颜色和名字徽章**（`prod` 红色、`staging` 琥珀色）、
+  可配置的头部、自定义提示音，以及在格子里直接启动项目脚本、`.claude/skills` 和 deck 的
+  Run / Skill / Mulmo 菜单。
+
+![MulmoTerminal 的网格视图 —— 四个 Claude 会话并排运行，各自属于不同颜色的项目](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/grid-2x2-live.png)
+
+*网格就是**并行智能体的驾驶舱**。每个格子的头部摆着你做判断需要的东西 ——
+**模型 · 上下文 %**、**token 数**（`⇡in ⇣out`）、**git 分支 / 变更**标签，
+以及这个智能体正在做什么的 AI 摘要。**格子的边框颜色表示状态**，屏幕外卡住的格子会用声音把你叫回来。*
+
+### 底层是怎么回事
+
+每个会话在服务器上作为真实的 PTY 运行（把智能体 CLI 放进一个伪终端），
+通过 WebSocket 流到浏览器里的 [xterm.js](https://xtermjs.org/) 终端。
+
+**cockpit roster** 列出所有会话，并实时反映哪些**在跑**（智能体在思考）、
+哪些**在等你**（权限确认或提问 —— 琥珀色圆点，你不答它就不往下走）、
+哪些**跑完了但你还没看**（绿色圆点）。这些来自**服务器在启动会话时注入的
+Claude / Codex activity hook**，不是去解析屏幕上的文字。
+
+> 这是关键。在终端里，「卡在权限确认上」和「还在思考」**看起来完全一样** ——
+> 两者都只是不再输出了。读屏幕分不出来，hook 可以。
+>
+> （Codex 不上报「等待输入」：它的确认框画在自己的 TUI 里，不会进 rollout 文件。
+> 所以对 Codex 来说只有「在跑 / 跑完了」两种状态。）
+
+## 换过来的人怎么说
+
+> 以下是从 IDE 或分屏终端迁移过来的用户的反馈，不是基准测试，也不是我们测量过的结论。
+> 你的环境可能不同。
+
+**「它不再吃我的内存了」** —— 靠开多个 IDE 窗口来隔离智能体的代价很高：
+每个窗口都带上自己的编辑器、语言服务器、扩展和文件监听。有用户反馈说
+**64GB 的机器在那种负载下会卡**，换过来之后就顺了。在这里智能体是服务器上的 PTY，
+界面是浏览器标签页。
+
+**「我不再回错智能体了」** —— 六个滚动文字的 pane 长得一模一样。
+有用户描述过**把回复打进了另一个智能体的终端**，并且想不起来最初让它做什么。
+问题不在注意力，而在于 N 个相同的 pane 意味着要在脑子里保持 N 份上下文。
+状态着色、名字徽章和按目录的颜色，把这件事从脑子里搬到了屏幕上。
+
+**「看很多和读一个不再是二选一」** —— 把终端切成六份，每个 pane 都小到读不完一段长回复
+（有用户碰到的是 4000 字的回复）。于是每加一个智能体，你就默默接受更差的阅读体验。
+**网格 ↔ 放大**去掉了这个取舍：先看全部，再把一个放大好好读，
+期间 cockpit roster 仍然以文字形式保留其余的。
+
+**「我原有的会话跟着一起过来了」** —— 会话原样恢复（同样的 `claude --resume`，同样的记录）。
+指向一个你本来就在用的目录，历史就在那里。不用迁移，也不用重做。
+
+**不需要十个智能体才划算。** 有用户反馈在并行 **1 到 3** 个会话时就已经值得换过来。
+上面这些好处讲的是「不再跟丢」，不是「跑得更多」。
+
+## 安装与运行
+
+需要 **Node 22.12 以上**，以及 `PATH` 上的这些 CLI：
+
+| | 工具 | 它带来什么 | 安装 |
+| --- | --- | --- | --- |
+| **必需** | [`claude`](https://claude.com/claude-code) | 所有 Claude 会话，本应用是它的驾驶舱 | `npm i -g @anthropic-ai/claude-code`，然后跑一次 `claude` 登录 |
+| **必需** | `git` | worktree 隔离、每格的分支 / 未保存点 / diff、PR footer | `brew install git` · `sudo apt install git` · Windows: [git-scm.com](https://git-scm.com/download/win) |
+| **必需** | `gh` | 跨仓库的 **PR & Issue** 视图和一键开 PR。用你自己的 `gh` 登录，不存 token | [cli.github.com](https://cli.github.com)，然后 `gh auth login` |
+| 可选 | `glab` | 对 **GitLab** 项目做同样的事，支持自建实例 | `brew install glab`，然后 `glab auth login` |
+| 推荐 | `tmux` | **会话持久化** —— 终端能挺过服务器重启 | `brew install tmux` · `sudo apt install tmux` · Windows 无原生版本（退回普通 PTY） |
+| 可选 | `codex` | 在格子里跑 **Codex 会话** | `npm i -g @openai/codex` |
+| 可选 | `ffmpeg` | 从 mulmo-script 面板渲染视频 | `brew install ffmpeg` · `sudo apt install ffmpeg` |
+| 可选 | `ollama` | 用完全本地的模型跑 Claude Code | [ollama.com/download](https://ollama.com/download) |
+
+缺少非必需的行，服务器照样启动，只是少掉那一行的功能，并且界面会说明。
+
+```bash
+npx mulmoterminal@latest           # 在 http://localhost:34567 启动并打开浏览器
+# 或者全局安装：
+npm install -g mulmoterminal
+mulmoterminal
+```
+
+**怎么停。** 在启动它的终端按 `Ctrl+C`；找不到那个终端的话，用浏览器里的
+**Settings → Quit MulmoTerminal**，或者在任意终端跑 **`npx mulmoterminal@latest stop`**。
+装了 `tmux` 的话智能体会话会活下来，从 **Settings → Sessions that survived a restart** 回来。
+
+**首次配置（可选）。** `npx mulmoterminal@latest init` 会检查环境，
+从你的 Claude Code 历史里生成启动器的**目录预设**，并写入 `~/.mulmoterminal/config.json`。
+它是**幂等的**，想刷新预设随时可以再跑一次。
+
+## 文档
+
+**[receptron.github.io/mulmoterminal](https://receptron.github.io/mulmoterminal/)**
+
+- **用户指南（英文）:** [English](https://receptron.github.io/mulmoterminal/guide/en/) ——
+  网格视图、日常工作流、完整功能列表、配置、手机推送
+- **用户指南（日文）:** [日本語](https://receptron.github.io/mulmoterminal/guide/ja/)
+- **更新:** 新版本和新功能在 X 上发布 ——
+  英文 [@mulmocast](https://x.com/mulmocast)，日文
+  [Singularity Society (@SingularitySoci)](https://x.com/SingularitySoci)
+
+## 谁在做
+
+**[receptron](https://github.com/receptron)** ——
+在微软担任 **Windows 95** 软件架构师的
+**[中島聡 (Satoshi Nakajima)](https://x.com/snakajima)**
+和 **[有本勇 (Isamu Arimoto)](https://github.com/isamu)**，
+也就是做 **[GraphAI](https://github.com/receptron/graphai)** 的同一组人。
+
+## 许可证
+
+MIT
+
+---
+
+> **本文对应英文 README 的前约 360 行（产品介绍与安装）。**
+> 配置、架构、脚本、skills、deck、worktree 与 PR、远程主机等细节，
+> 请看[英文 README](README.md) 和[用户指南](https://receptron.github.io/mulmoterminal/guide/en/)。

package/bin/agent-bins.d.ts

@@ -0,0 +1,15 @@
+// Types for bin/agent-bins.js — hand-written for the reason every other bin/*.d.ts is: the file is
+// plain JS because it runs before tsx does, and the specs and the server are TypeScript.
+import type { TerminalAgent } from "../common/sessionAgent.js";
+
+export interface AgentBinSpec {
+  /** The environment variable that overrides the command, e.g. `CLAUDE_BIN`. */
+  env: string;
+  /** The command as installed. NOT always the agent id — agy and cursor-agent are the commands. */
+  bin: string;
+}
+
+export declare const AGENT_BIN_SPEC: Record<TerminalAgent, AgentBinSpec>;
+export declare function agentBin(agent: string, env?: Record<string, string | undefined>): string | null;
+/** Only the agents this repository documents an install command for. */
+export declare const AGENT_INSTALL_HINT: Partial<Record<TerminalAgent, string>>;

package/bin/agent-bins.js

@@ -0,0 +1,38 @@
+// Which binary each hosted agent runs, and the environment variable that overrides it.
+//
+// Here in `bin/` rather than in `server/` because the CLI needs it BEFORE the server exists: the
+// start-up gate has to decide whether the declared agent is installed, and it runs under plain node
+// with no tsx. The server imports from `bin/` already (bin/instances.js), so this direction is the
+// established one.
+//
+// The table is duplicated knowledge by construction — `server/config/agent-bins.ts` builds the same
+// mapping out of the adapters — so a spec pins the two together rather than a comment asking the
+// next person to keep them in sync.
+//
+// The KEY is the agent id and the `bin` is NOT always the same word: agy and cursor-agent are the
+// commands, `antigravity` and `cursor` are what the rest of the app calls them.
+export const AGENT_BIN_SPEC = {
+  claude: { env: "CLAUDE_BIN", bin: "claude" },
+  codex: { env: "CODEX_BIN", bin: "codex" },
+  antigravity: { env: "ANTIGRAVITY_BIN", bin: "agy" },
+  grok: { env: "GROK_BIN", bin: "grok" },
+  muse: { env: "MUSE_BIN", bin: "muse" },
+  copilot: { env: "COPILOT_BIN", bin: "copilot" },
+  cursor: { env: "CURSOR_BIN", bin: "cursor-agent" },
+};
+
+/** The command that actually runs for `agent`, honouring its `<AGENT>_BIN` override. */
+export function agentBin(agent, env = process.env) {
+  const spec = AGENT_BIN_SPEC[agent];
+  if (spec === undefined) return null;
+  return env[spec.env] || spec.bin;
+}
+
+/** The install command for the agents this repository actually documents one for — Claude Code in
+ *  the start-up gate's own message, codex in PATH_TOOLS. The other five are deliberately ABSENT
+ *  rather than guessed: an install line that is wrong is worse than none, because it is the one
+ *  thing a stuck user will paste. They get the binary name and the guide link instead. */
+export const AGENT_INSTALL_HINT = {
+  claude: "npm install -g @anthropic-ai/claude-code  &&  claude auth login",
+  codex: "npm install -g @openai/codex",
+};

package/bin/cli-args.d.ts

@@ -16,7 +16,7 @@ export declare function saysYes(answer: unknown): boolean;
 export declare const SECOND_INSTANCE_NOTE: string;
 export declare const MIN_NODE_LABEL: string;
 export declare function nodeMeetsMinimum(version: string): boolean;
-export declare function serverNodeArgs(serverEntry: string, launchDir: string, port: number): string[];
+export declare function serverNodeArgs(serverEntry: string, launchDir: string, port: number, declaredAgent?: string | null): string[];
 export declare function serverSpawnEnv(env: Record<string, string | undefined>, cwd: string): Record<string, string | undefined>;
 export interface RunningInstance {
   pid: number;

package/bin/cli-args.js

@@ -426,9 +426,14 @@ export function nodeMeetsMinimum(version) {
  * MulmoTerminal's own port (#1857). Renaming it would only move that: `MULMOTERMINAL_PORT` is
  * deliberately given to PTYs (server/session/mcp-config.ts) for the MCP URLs, so a server
  * reading it as its bind port would clash with itself the moment `yarn dev` ran inside a cell.
+ *
+ * `--agent` rides the same channel for the same reason (#2082): it is a preference, and a
+ * preference in the environment would reach every terminal in every cell exactly as the port did.
+ * Omitted entirely when nothing was declared, so the server falls through to its config file.
  */
-export function serverNodeArgs(serverEntry, launchDir, port) {
-  return ["--import", "tsx", `--env-file-if-exists=${join(launchDir, ".env")}`, serverEntry, "--port", String(port)];
+export function serverNodeArgs(serverEntry, launchDir, port, declaredAgent = null) {
+  const base = ["--import", "tsx", `--env-file-if-exists=${join(launchDir, ".env")}`, serverEntry, "--port", String(port)];
+  return declaredAgent === null ? base : [...base, "--agent", declaredAgent];
 }
 
 /**

package/bin/default-agent.d.ts

@@ -0,0 +1,19 @@
+// Types for bin/default-agent.js. See that file for why the gate works the way it does.
+import type { TerminalAgent } from "../common/sessionAgent.js";
+
+export interface StartupGate {
+  /** Whose binary start-up must find. */
+  agent: TerminalAgent;
+  /** Always true today; named so a future "warn instead" cannot be added by accident. */
+  required: boolean;
+  /** Whether the user asked for this agent, which changes what the failure says. */
+  declared: boolean;
+}
+
+export declare function isKnownAgent(value: unknown): value is TerminalAgent;
+/** The raw token after `--agent`, `""` for a valueless flag, or null when absent. */
+export declare function parseAgentArg(args: readonly string[]): string | null;
+export declare function resolveDeclaredAgent(input?: { cliAgent?: string | null; configAgent?: string | null }): string | null;
+export declare function gateFor(declaredAgent: string | null): StartupGate;
+export declare function configuredDefaultAgent(parsedConfig: unknown): string | null;
+export declare function missingAgentMessage(gate: StartupGate, bin: string | null): string[];