mulmoterminal 5.3.0 → 5.4.0

package/README.ja.md

@@ -1,6 +1,6 @@
 # MulmoTerminal
 
-[English](README.md) · **日本語** · [简体中文](README.zh.md)
+[English](README.md) · **日本語** · [简体中文](README.zh.md) · [繁體中文](README.zh-TW.md) · [한국어](README.ko.md)
 
 **コーディングエージェントのセッションを並列で走らせ、どれが自分を待っているかを見る。**
 
@@ -40,7 +40,7 @@ MulmoTerminal では、すべてのセルが自分の状態を一つのグリッ
 作業中（青）、完了（緑）、**あなた待ち**（琥珀）。画面外のセルが琥珀になれば音が鳴ります。
 さらに**1セッション1行の cockpit roster** があるので、1つに答えている間も残り4つを見失いません。
 
-tmux が入っていればその**上で**動き、[再起動を越えて残ります](#セッションの永続化-tmux)。
+tmux が入っていればその**上で**動き、[再起動を越えて残ります](README.md#session-persistence-tmux)。
 
 ## なぜ欲しくなるか
 

package/README.ko.md

@@ -0,0 +1,182 @@
+# MulmoTerminal
+
+[English](README.md) · [日本語](README.ja.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-TW.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로도 됩니다. 놓치는 것은
+**다섯 중에 어느 것이 당신을 기다리는가**입니다. 창 하나는 불투명합니다.
+도는 중인지, 끝났는지, 권한 확인에서 멈춰 있는지 —— 읽어 보기 전에는 구분이 안 됩니다.
+
+MulmoTerminal에서는 각 칸이 자기 상태를 같은 그리드에 보고합니다 ——
+도는 중(파랑), 끝남(초록), **당신을 기다림**(호박색). 화면 밖 칸이 호박색으로 바뀌면 소리가 납니다.
+거기에 **세션마다 한 줄인 cockpit roster**가 있어서, 그중 하나에 답하는 동안에도
+나머지 넷의 자리를 놓치지 않습니다.
+
+tmux가 깔려 있으면 그 **위에서** 돌고, [재시작도 견딥니다](README.md#session-persistence-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이고, 화면은 브라우저 탭입니다.
+
+**"이제 엉뚱한 에이전트에 답하지 않는다"** —— 글자가 흐르는 창 여섯 개는 생김새가 똑같습니다.
+어떤 사용자는 **다른 에이전트의 터미널에 답을 쳐 넣었고**, 애초에 그것에 무엇을 시켰는지조차
+기억나지 않았다고 했습니다. 주의력의 문제가 아니라, 똑같은 창 N개가 머릿속에 N개의 맥락을
+들고 있으라는 뜻이기 때문입니다. 상태 색, 이름 배지, 디렉터리별 색이 그 일을 머릿속에서 화면으로 옮깁니다.
+
+**"많이 보기와 하나를 읽기가 더는 양자택일이 아니다"** —— 터미널을 여섯으로 쪼개면
+각 창이 긴 답변 하나를 다 읽기에도 작습니다. 그래서 에이전트를 하나 더할 때마다
+읽기 경험이 나빠지는 것을 말없이 받아들이게 됩니다. **그리드 ↔ 확대**는 그 맞바꿈을 없앱니다.
+먼저 전부 보고, 하나를 확대해 제대로 읽으며, 그동안에도 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` 로그인을 쓰고 토큰을 저장하지 않습니다 | [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 앞부분의 제품 소개와 설치에 해당합니다.**
+> 설정, 아키텍처, 스크립트, skills, deck, worktree와 PR, 원격 호스트 같은 세부는
+> [영문 README](README.md)와 [사용자 가이드](https://receptron.github.io/mulmoterminal/guide/en/)를 보세요.

package/README.md

@@ -1,6 +1,6 @@
 # MulmoTerminal
 
-**English** · [日本語](README.ja.md) · [简体中文](README.zh.md)
+**English** · [日本語](README.ja.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-TW.md) · [한국어](README.ko.md)
 
 **Run multiple coding-agent sessions in parallel — and see which one needs you.**
 
@@ -97,7 +97,8 @@ the same two behind **[GraphAI](https://github.com/receptron/graphai)**. [More
   tap (**yes / no / continue**) from the phone itself — walk away, get pinged, jump back in.
 - **Nothing is lost on a restart.** With `tmux`, every session survives a server crash,
   restart, or `node --watch` reload — a mid-turn agent, a long build, a dev server all keep
-  running and reattach when you come back.
+  running and reattach when you come back. A crashed server is restarted for you, so the
+  tab you left open finds it again.
 - **Ship without leaving the grid.** Each repo cell shows a **git branch chip**, isolates
   work in a one-click **git worktree**, opens a **diff** panel, and does **commit / push /
   open PR** — so several agents can work the same repo without colliding.
@@ -169,7 +170,7 @@ than as bytes (files within the session's working directory only):
 
 | A clicked … | opens as |
 |---|---|
-| `.md` `.markdown` | **rendered** markdown in a new tab — the same sandboxed `…/md` HTML the Files preview uses. It follows your system light/dark setting, since under the sandbox CSP it can't ask the app which theme is on |
+| `.md` `.markdown` | **rendered** markdown in a new tab — the same sandboxed `…/md` HTML the Files preview renders, minus the one script the preview needs to report where you are reading. It follows your system light/dark setting, since under the sandbox CSP it can't ask the app which theme is on |
 | `.json` | **indented** in a new tab (Chrome and Safari otherwise show one long line) |
 | `.csv` `.tsv` | a **table** in a new tab, with a sticky header that scrolls inside its own box |
 | source, config, logs, and `.txt` — 46 extensions | the app's own **Files** view (`/files?path=`), where CodeMirror highlights it, the tree is right there, and it can be edited |
@@ -629,6 +630,18 @@ A long build, a dev server, or a mid-turn Claude session all survive `node --wat
 reloads and crashes. It uses its **own** tmux server (`-L mulmoterminal`) and config, so
 it never touches your personal tmux sessions or keybindings.
 
+**And the server comes back by itself.** `npx mulmoterminal` supervises the server it
+started: a crash is restarted with a short backoff, so the browser tab reconnects to the
+sessions tmux kept rather than to a dead port — which matters most from a phone, where
+there is no terminal to start it again in. A stop you asked for is still a stop:
+`mulmoterminal stop`, the Stop button, Ctrl+C and `kill` all end it. A server that never
+managed to bind is not restarted either — the reason it printed is the answer, and
+retrying would bury it. Repeated failures give up rather than respawn forever.
+
+**Not on Windows**, where it is not yet possible: Node has no real signals there, so every
+way of stopping the server terminates it outright, and the launcher cannot tell that from
+a crash. Windows keeps the old behaviour — the launcher ends when its server does.
+
 **No tmux? No problem** — terminals fall back to plain (non-persistent) PTYs, exactly as
 before. An explicit close (a cell's ✕) ends the tmux session; a machine reboot does not
 survive (tmux itself is gone). Command-cell scripts are ephemeral and not persisted.
@@ -1251,8 +1264,10 @@ on, and how far down the tree was scrolled. The top line matters on its own —
 neither the selection nor the caret, so someone reading without clicking would otherwise come back
 to the top of a file they were in the middle of. The caret is kept as a line rather than a scroll offset, so it survives
 the pane being a different width next time, and a line past the end of a file that has since been
-edited lands on the nearest real one. The Markdown preview's own scroll position is not remembered
-— its iframe is sandboxed to the point where the app cannot read it.
+edited lands on the nearest real one. The Markdown preview's own scroll position comes back too,
+and as a pixel offset rather than a line, because a rendered document has no lines in it. The app
+still cannot read that frame — it stays sandboxed with no `allow-same-origin`, so the position is
+reported BY the document, through the one script the server is allowed to put in it.
 
 **It also paints before it has finished reading.** The last listing of each directory is kept, so
 opening the pane on one you have been to before shows that tree at once and swaps in what the

package/README.zh-TW.md

@@ -0,0 +1,172 @@
+# MulmoTerminal
+
+[English](README.md) · [日本語](README.ja.md) · [简体中文](README.zh.md) · **繁體中文** · [한국어](README.ko.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 就做得到。丟掉的是**五個裡面哪一個在等你**。
+一個窗格是不透明的：執行中、跑完了、卡在權限確認上 —— 不讀一遍就分不出來。
+
+在 MulmoTerminal 裡，每一格都把自己的狀態回報給同一個網格 ——
+執行中（藍）、跑完了（綠）、**等你**（琥珀）。螢幕外的格子轉琥珀色時會響一聲。
+還有一個**每個工作階段一列的 cockpit roster**，所以你在回答其中一個的時候，
+不會弄丟另外四個的位置。
+
+裝了 tmux 的話它就跑在 tmux **之上**，[重啟也不會丟](README.md#session-persistence-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，
+介面是瀏覽器分頁。
+
+**「我不再回錯代理程式了」** —— 六個捲動文字的窗格長得一模一樣。
+有使用者描述過**把回覆打進了另一個代理程式的終端機**，而且想不起來最初讓它做什麼。
+問題不在注意力，而在於 N 個相同的窗格意味著要在腦子裡保持 N 份上下文。
+狀態著色、名稱徽章和依目錄的顏色，把這件事從腦子裡搬到了螢幕上。
+
+**「看很多和讀一個不再是二選一」** —— 把終端機切成六份，每個窗格都小到讀不完一段長回覆。
+於是每加一個代理程式，你就默默接受更差的閱讀體驗。
+**網格 ↔ 放大**去掉了這個取捨：先看全部，再把一個放大好好讀，
+其間 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 開頭的產品介紹與安裝部分。**
+> 設定、架構、指令碼、skills、deck、worktree 與 PR、遠端主機等細節，
+> 請看[英文 README](README.md) 和[使用者指南](https://receptron.github.io/mulmoterminal/guide/en/)。

package/README.zh.md

@@ -1,6 +1,6 @@
 # MulmoTerminal
 
-[English](README.md) · [日本語](README.ja.md) · **简体中文**
+[English](README.md) · [日本語](README.ja.md) · **简体中文** · [繁體中文](README.zh-TW.md) · [한국어](README.ko.md)
 
 **并行跑多个编码智能体会话 —— 一眼看出哪一个在等你。**
 
@@ -38,7 +38,7 @@ npx mulmoterminal@latest        # 在 http://localhost:34567 启动并打开浏
 还有一个**每个会话一行的 cockpit roster**，所以你在回答其中一个的时候，
 不会丢掉另外四个的位置。
 
-装了 tmux 的话它就跑在 tmux **之上**，[重启也不会丢](#会话持久化-tmux)。
+装了 tmux 的话它就跑在 tmux **之上**，[重启也不会丢](README.md#session-persistence-tmux)。
 
 ## 为什么你会想要它