mulmoterminal 0.6.2 → 0.8.0

package/Dockerfile.sandbox

@@ -0,0 +1,30 @@
+# MulmoTerminal sandbox image: runs the interactive `claude` CLI inside a container so
+# an untrusted workspace can't touch the host. Deliberately minimal — unlike MulmoClaude
+# this image needs NO in-container MCP broker, because MulmoTerminal's GUI MCP is served
+# over HTTP by the host and reached at host.docker.internal (see docs/spawn-architecture).
+#
+# What's inside: node (for the claude CLI), curl (the activity hooks POST to the host),
+# git + ripgrep + ca-certificates (claude's built-in tools). No secrets, no host FS.
+FROM node:22-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      git \
+      curl \
+      ca-certificates \
+      ripgrep \
+    && rm -rf /var/lib/apt/lists/*
+
+# The interactive agent CLI. Pin nothing here — a rebuild picks up the latest, matching
+# how the host runs the newest `claude`.
+RUN npm install -g @anthropic-ai/claude-code
+
+# Run as the unprivileged `node` user (uid 1000). Phase 1 is macOS-only: Docker Desktop
+# maps bind-mount ownership transparently there. The server gates the sandbox off on Linux
+# (no `--user` yet → uid-1000 ownership mismatch) and Windows (host paths aren't valid
+# Linux container paths), falling back to the host spawn — see Phase 5 (#202).
+USER node
+ENV HOME=/home/node
+WORKDIR /home/node/workspace
+
+# The host passes `claude ...` (with a rewritten --mcp-config / --settings) as the
+# command, so no ENTRYPOINT/CMD baked in — the container IS one claude session.

package/README.md

@@ -1,14 +1,21 @@
 # mulmoterminal
 
-A browser-based terminal for running [Claude Code](https://claude.com/claude-code)
-sessions, with a sidebar that lists the current project's chat sessions and shows
-live, hook-driven activity for each one.
+A browser-based terminal + GUI workspace for coding agents — [Claude Code](https://claude.com/claude-code)
+and OpenAI's **Codex** — with a sidebar that lists the current project's chat sessions
+and shows live, hook-driven activity for each one.
 
-Each session runs as a real PTY on the server (`claude` in a pseudo-terminal) and
+Each session runs as a real PTY on the server (the agent CLI in a pseudo-terminal) and
 is streamed to an [xterm.js](https://xtermjs.org/) terminal in the browser over a
-WebSocket. A sidebar lists every Claude session for the project and reflects, in
-real time, which sessions are **working** (Claude is thinking) and which **need
-attention** (waiting for input, or finished with output you haven't seen).
+WebSocket. A sidebar lists every session for the project and reflects, in real time,
+which sessions are **working** (the agent is thinking) and which **need attention**
+(waiting for input, or finished with output you haven't seen).
+
+Around the terminal sit the things a coding session needs: a **grid** of parallel
+sessions, an optional **GUI panel** for rich tool output (documents, forms, images,
+charts), **git worktree** isolation with one-click **push / open PR**, a full-screen
+**file browser + editor**, per-session **cost & token** readouts, a cross-repo **PRs &
+Issues** view, and read-only **Wiki** and **Collections** browsers over the shared
+workspace.
 
 **Inserting a file path** — like a native terminal, you can put a file's absolute
 path into the prompt: **drag a file** onto the terminal (works where the browser
@@ -22,7 +29,10 @@ inserted at the cursor — it is not submitted, so you can review it first.
 ## Install & run
 
 Requires the [`claude`](https://claude.com/claude-code) CLI on your `PATH` and
-**Node ≥ 22.9**.
+**Node ≥ 22.9**. Optional but recommended: **`tmux`** so terminals survive a server
+restart (see [Session persistence (tmux)](#session-persistence-tmux)), the **`gh`** CLI
+logged in for the PRs/Issues view and one-click PR creation, and — for Codex sessions —
+the **`codex`** CLI on your `PATH`.
 
 ```bash
 npx mulmoterminal           # start on http://localhost:34567 and open the browser
@@ -54,15 +64,26 @@ server, and opens the browser. For local development from a clone, see
 
 - [Architecture](#architecture)
 - [Why a PTY?](#why-a-pty)
+- [Agents: Claude & Codex](#agents-claude--codex)
+- [Session persistence (tmux)](#session-persistence-tmux)
+- [Docker sandbox (experimental, single view)](#docker-sandbox-experimental-single-view)
 - [Tech stack](#tech-stack)
 - [Configuration](#configuration)
 - [Running](#running)
 - [Scripts (Run menu)](#scripts-run-menu)
+- [Files view (browse & edit)](#files-view-browse--edit)
+- [Git worktrees & pull requests](#git-worktrees--pull-requests)
+- [Cost & token usage](#cost--token-usage)
+- [Wiki, Collections & the GUI panel](#wiki-collections--the-gui-panel)
+- [More features](#more-features)
 - [Server API specification](#server-api-specification)
   - [HTTP: `GET /api/sessions`](#http-get-apisessions)
   - [HTTP: `GET /api/scripts`](#http-get-apiscripts)
+  - [HTTP: `POST /api/command/summarize`](#http-post-apicommandsummarize)
   - [HTTP: `POST /api/hook`](#http-post-apihook)
+  - [More HTTP endpoints](#more-http-endpoints)
   - [WebSocket: `/ws` (terminal)](#websocket-ws-terminal)
+  - [More WebSocket endpoints](#more-websocket-endpoints)
   - [WebSocket: `/ws/run` (command terminal)](#websocket-wsrun-command-terminal)
   - [Socket.IO: `/ws/pubsub` (activity pub/sub)](#socketio-wspubsub-activity-pubsub)
 - [Session model](#session-model)
@@ -93,14 +114,15 @@ server, and opens the browser. For local development from a clone, see
 - **Session list** is fetched over HTTP (`/api/sessions`).
 - **Live activity** is pushed over a Socket.IO pub/sub channel (`/ws/pubsub`);
   the server learns of activity from **Claude hooks** that POST to `/api/hook`.
-- **Script commands** (`yarn dev`, tests, …), launched from a cell's directory
-  picker, run in their own ephemeral PTY over a separate WebSocket (`/ws/run`);
-  they are not Claude sessions. See [Scripts (Run menu)](#scripts-run-menu).
+- **Other terminals** run on their own raw WebSockets: **Codex** sessions on `/ws/codex`,
+  persistent **launch commands** on `/ws/launch`, and one-off **script commands**
+  (`yarn dev`, tests, …) on `/ws/run`. Only Claude/Codex are agent sessions with hooks;
+  see [Agents: Claude & Codex](#agents-claude--codex) and [Scripts (Run menu)](#scripts-run-menu).
 - In dev (`yarn dev`) the Vite dev server runs on its own port (`CLIENT_PORT`,
-  default `6856`) and proxies `/ws` (covers `/ws/run`), `/ws/pubsub`, and `/api` to
-  the backend (`PORT`, default `34567`) — so you open the Vite port (e.g.
-  `http://localhost:6856`). In production the backend serves the built client from
-  `dist/` on `PORT`, and you open that.
+  default `6856`) and proxies `/ws` (a prefix covering `/ws/codex`, `/ws/launch`, and
+  `/ws/run`), `/ws/pubsub`, `/api`, and `/artifacts` to the backend (`PORT`, default
+  `34567`) — so you open the Vite port (e.g. `http://localhost:6856`). In production the
+  backend serves the built client from `dist/` on `PORT`, and you open that.
 
 ---
 
@@ -121,6 +143,38 @@ SDK; we drive the real interactive CLI and relay its TTY over the WebSocket.
 
 ---
 
+## Agents: Claude & Codex
+
+MulmoTerminal drives **interactive coding-agent CLIs**, not just Claude. An
+`AgentAdapter` seam abstracts the per-agent bits (which binary to spawn, how it resumes)
+so the PTY, grid, persistence, and GUI-panel plumbing stay shared. Two adapters ship
+today — **Claude Code** (the default) and **Codex**.
+
+- **Claude** — spawned as `claude` (override with `CLAUDE_BIN`). The server passes
+  `--session-id <uuid>`, so it knows the live session's id even before its transcript
+  file exists, and injects activity hooks + the GUI MCP per spawn (see
+  [Claude hook injection](#claude-hook-injection)).
+- **Codex** — spawned as `codex` (override with `CODEX_BIN`; `CODEX_MODEL` sets
+  `--model`). Codex runs on its own WebSocket (`/ws/codex`) and its sessions appear in the
+  sidebar next to Claude's. Because Codex only mints its rollout id **after** the first
+  turn, the server watches `~/.codex/sessions/**/rollout-*.jsonl` (home overridable via
+  `CODEX_HOME`) and maps the new rollout to the session — attributed only when it's
+  unambiguous, never by "newest wins". Resume reattaches a live PTY, adopts a surviving
+  tmux session, or cold-resumes the rollout id.
+
+**Choosing an agent.** The single view has a **New Codex session** button; each grid
+cell's launch form and the Collections browser carry a **Claude / Codex** toggle (your
+choice is remembered).
+
+**Skills for Codex.** Codex has no `/<slug>` slash commands, so on session setup
+MulmoTerminal **mirrors the workspace's `.claude/skills` into `~/.codex/skills`** (each
+mirrored directory carries a `.mt-mirror` marker so a re-sync overwrites what MulmoTerminal
+owns and never clobbers Codex's own skills), and rewrites a collection's `/<slug> …` seed
+into a plain `Use the "<slug>" skill.` instruction. The same skills Claude uses then show
+up for Codex, loaded by description.
+
+---
+
 ## Session persistence (tmux)
 
 If **`tmux` is installed**, MulmoTerminal runs each Claude session and launcher inside
@@ -134,14 +188,68 @@ it never touches your personal tmux sessions or keybindings.
 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.
 
+**Installing tmux** (optional):
+
+```bash
+brew install tmux            # macOS (Homebrew)
+sudo apt install tmux        # Debian / Ubuntu
+sudo dnf install tmux        # Fedora
+```
+
+On Windows there's no native tmux, so sessions use the non-persistent fallback — run the
+server under **WSL** if you want persistence. Nothing else is required: MulmoTerminal
+detects `tmux` on `PATH` at startup and uses it automatically when present.
+
+---
+
+## Docker sandbox (experimental, single view)
+
+Set **`MULMOTERMINAL_SANDBOX=1`** (and have Docker running) to run the **single-view**
+Claude session inside a container instead of on the host, while Claude still reaches the
+app's GUI MCP + activity hooks over `host.docker.internal`. The `mulmoterminal-sandbox`
+image is **built automatically** on first launch from the shipped `Dockerfile.sandbox`
+(~1 min, once; rebuilt only when that file changes). Override the name with
+`MULMOTERMINAL_SANDBOX_IMAGE`. If the image can't be built (e.g. Docker down), the session
+falls back to the host spawn — no cryptic failure.
+
+This **contains** Claude — it can't reach the host filesystem outside the mounts, host
+processes, or arbitrary host ports. It is **not full isolation**: the **workspace** and
+**`~/.claude`** are bind-mounted **read-write** by design (so Claude edits your project,
+and transcripts interoperate with host sessions), so those specific paths stay mutable
+from inside. The sandbox is **non-persistent** (the container is
+`--rm`, tied to the session), **opt-in and single-view only** — the grid keeps its host +
+tmux path, and with the flag unset (or Docker unavailable) everything runs on the host
+exactly as before. **macOS only** for now — on Linux (bind-mount uid ownership) and
+Windows (host paths aren't valid Linux container paths) it falls back to the host spawn;
+both are follow-ups. Adding arbitrary user MCP servers to the sandbox is in progress
+(see #202).
+
+**Authentication (macOS).** Claude's live login token lives in the macOS **Keychain**,
+which the container can't read (mounting `~/.claude` alone isn't enough — its
+`.credentials.json` is often absent or stale). On each sandbox spawn MulmoTerminal exports
+the current credential to a per-session `~/.mulmoterminal/sandbox/creds-<id>.json`
+(mode `0600`, removed when the session ends) and mounts it **read-only** over the
+container's `~/.claude/.credentials.json`; your host `~/.claude` is never modified. If
+you've never logged in on the host, run `claude` once first — otherwise the server logs a
+warning and the container shows "Not logged in".
+
+**Host credentials (opt-in).** By default the sandbox has no host credentials. To let the
+sandboxed Claude use `gh`/`git`, set **`SANDBOX_MOUNT_CONFIGS=gh,gitconfig`** — a **fixed
+allowlist** (you pick names, never arbitrary paths): `gh` mounts `~/.config/gh` read-only
+and passes a `GH_TOKEN` (from `gh auth token`, since macOS keeps it in the Keychain), and
+`gitconfig` mounts `~/.gitconfig` read-only. Set **`SANDBOX_SSH_AGENT_FORWARD=1`** to
+forward the SSH agent socket (the keys never enter the container). Both are read only when
+building the sandbox spawn, so they have no effect unless `MULMOTERMINAL_SANDBOX` is on.
+
 ---
 
 ## Tech stack
 
 | Layer    | Technology |
 | -------- | ---------- |
-| Frontend | Vue 3 (`<script setup>` + TypeScript), Vite, xterm.js (`@xterm/*`), socket.io-client |
-| Backend  | Node (ESM, TypeScript run via `tsx`), Express 5, `ws` (terminal WebSocket), `node-pty`, socket.io |
+| Frontend | Vue 3 (`<script setup>` + TypeScript), Vue Router, Vite, xterm.js (`@xterm/*`), CodeMirror 6, socket.io-client |
+| Backend  | Node (ESM, TypeScript run via `tsx`), Express 5, `ws` (terminal WebSocket), `node-pty`, socket.io, `@modelcontextprotocol/sdk` (in-process GUI MCP) |
+| Plugins  | GUI-protocol Vue plugins (`@mulmoclaude/*`, `@mulmochat-plugin/*`): markdown, form, image, chart, HTML, collection, accounting |
 | Tests    | Vitest + @vue/test-utils + jsdom |
 
 Requires **Node ≥ 22.9** (uses `node --env-file-if-exists`) and the `claude` CLI on `PATH`.
@@ -161,6 +269,17 @@ the server runs without one.
 | `CLIENT_PORT` | `6856`         | Vite dev-server port (dev only: the URL you open with `yarn dev`). |
 | `CLAUDE_BIN` | `claude`       | The Claude Code binary to spawn. |
 | `CLAUDE_CWD` | current dir    | Working directory each `claude` PTY runs in; determines which project's sessions the sidebar lists. Via `npx mulmoterminal` it defaults to the directory you ran the command from (override with `--cwd <dir>`, relative allowed); when the server is run directly it falls back to `~/mulmoclaude`. A value read from `.env` must be an absolute path (`~` is not expanded). |
+| `CLAUDE_PERMISSION_MODE` | `auto` | Permission mode passed to each `claude` spawn. |
+| `CODEX_BIN`  | `codex`        | The Codex CLI binary to spawn. |
+| `CODEX_MODEL`| codex default  | Model passed to Codex as `--model` (unset = Codex's own default). |
+| `CODEX_HOME` | `~/.codex`     | Codex home — where its session rollouts and MulmoTerminal-mirrored skills live. |
+| `MULMOTERMINAL_HOME` | `~/.mulmoterminal` | Root for managed **git worktrees**. |
+| `WAIT_REAP_GRACE_MS` | `1800000` | How long a **waiting** background session is kept before it's auto-reaped (`0` or negative = never). |
+
+The Docker-sandbox variables (`MULMOTERMINAL_SANDBOX`, `MULMOTERMINAL_SANDBOX_IMAGE`,
+`SANDBOX_MOUNT_CONFIGS`, `SANDBOX_SSH_AGENT_FORWARD`) and the update-check opt-outs
+(`MULMOTERMINAL_NO_UPDATE_CHECK`, `NO_UPDATE_NOTIFIER`) are covered in
+[Docker sandbox](#docker-sandbox-experimental-single-view) and [Install & run](#install--run).
 
 Example `.env` (gitignored):
 
@@ -179,6 +298,7 @@ The Settings modal (⚙) persists per-user UI choices to `~/.mulmoterminal/confi
 | `soundFile`  | Absolute path to a custom **attention sound** (played when a session needs attention). Empty/unset uses the built-in synthesized chime. |
 | `prRepos`    | `owner/repo` entries whose open PRs/issues the cross-repo **PRs & Issues** view aggregates (via your `gh` login). |
 | `launchers`  | `{ label, command }` entries offered in a grid cell's launcher besides Claude — a plain shell, `codex`, any interactive command. |
+| `userMcpServers` | `{ id, url }` HTTP MCP servers merged into the **single-view** Claude session's `--mcp-config` (a `localhost` URL is reached over `host.docker.internal` in the Docker sandbox). Takes effect on the next session. |
 
 **Attention sound.** The default chime is generated with the Web Audio API — **no
 audio file is bundled**, so the npm package stays light and has no media-licensing
@@ -199,6 +319,12 @@ malformed file is ignored.
 {
   "name": "PROD · payments",            // badge shown on this directory's terminals
   "badgeColor": "#cf222e",              // badge color (hex #rrggbb)
+  "headerColor": "#190a23",             // cell header background (hex #rrggbb)
+  "headerTextColor": "#ffffff",         // cell header text color (hex #rrggbb)
+  "cellColor": "#101014",               // cell body background (hex #rrggbb)
+  "cellBorderColor": "#2a2a4e",         // cell border color (hex #rrggbb)
+  "dotColor": "#00e676",                // idle status dot (hex #rrggbb)
+  "buttonColor": "#c7cdf0",             // header icon buttons (hex #rrggbb)
   "theme": "nord",                      // terminal palette: midnight | nord | daylight | solarized
   "colors": { "background": "#190a23", "cursor": "#ff2e63" }, // per-key palette overrides
   "sound": "./.mulmoterminal/alert.mp3" // attention sound, RELATIVE to this directory
@@ -209,6 +335,12 @@ malformed file is ignored.
 | ------------ | ------- |
 | `name`       | Label shown as a badge in the terminal/cell header. |
 | `badgeColor` | Badge background color (`#rrggbb`); text auto-contrasts. |
+| `headerColor` | Header **background** color (`#rrggbb`) — the grid cell's header row and the terminal's own header row (grid row 2 + single view). While a terminal is working/blocked the status tint still shows; the custom color applies when idle. |
+| `headerTextColor` | Header **text** color (`#rrggbb`) — the dir path, title, and prompt. |
+| `cellColor` | Cell **body background** color (`#rrggbb`) — the frame around the terminal. |
+| `cellBorderColor` | Cell **border** color (`#rrggbb`). The status frame (working/blocked) still overrides it while active. |
+| `dotColor` | **Idle** status-dot color (`#rrggbb`). The working/waiting colors are unchanged so the activity signal stays intact. |
+| `buttonColor` | Header **icon button** color (`#rrggbb`) — expand / close / attach / folder / etc., across both header rows. |
 | `theme`      | xterm palette for terminals in this directory (one of the built-in theme ids). |
 | `colors`     | Per-key xterm palette overrides applied on top of `theme` (or the app theme when `theme` is unset). Keys are xterm `ITheme` names (`background`, `foreground`, `cursor`, `selectionBackground`, the 16 ANSI colors, …); values are hex (`#rgb` / `#rrggbb` / `#rrggbbaa`). Unknown keys / bad values are dropped. |
 | `sound`      | Attention sound for this directory's sessions, a path **relative to the directory** (served at `GET /api/dir-sound`). |
@@ -300,6 +432,13 @@ offers a **↻ re-run**. The browser only ever sends the script's **index** + it
 directory; the server reads that directory's `script.json` and resolves the
 command, so the file is the allowlist of what can run.
 
+Each command cell also has a **✦ Summarize** button: click it to send the cell's
+captured output to `claude -p` (headless) and get a short **Errors / Warnings /
+likely cause / suggested fix** note in a panel — handy when a build or install
+buries the one failing line in thousands. It's manual (never auto-runs) and analyzes
+the last 32 KB of output. See
+[`POST /api/command/summarize`](#http-post-apicommandsummarize).
+
 ---
 
 ## Files view (browse & edit)
@@ -318,6 +457,119 @@ the terminal is pointed at.
 
 ---
 
+## Git worktrees & pull requests
+
+When a terminal's directory is a git repo, its header shows a **branch chip**
+(`⎇ <branch>` with dirty / ahead / behind counts), fed by `GET /api/git-status` (polled
+while the view is visible). A **GitHub** menu links straight to the repo, its issues, and
+its pull requests.
+
+**Worktree isolation.** A grid cell's launch form offers **＋ New worktree**: name a task
+and the cell launches its agent inside a fresh
+[git worktree](https://git-scm.com/docs/git-worktree) on a new `agent/<slug>` branch — a
+separate working tree that shares the repo's `.git`, so several agents can work the same
+repo without colliding. Worktrees live under `~/.mulmoterminal/worktrees/` (override with
+`MULMOTERMINAL_HOME`), and existing ones are listed for reuse.
+
+A worktree cell's header carries a **diff badge** (`+<commits> ●<dirty>`); click it for a
+**Changes vs `<base>`** panel (file list + patch) with actions:
+
+- **✓ Commit** — hands the cell's own session a canned commit prompt.
+- **⬆ Push** — `git push -u origin <branch>` (`POST /api/worktrees/push`).
+- **⧉ Open PR** — pushes, then `gh pr create … --fill`; if `gh` is missing or unauthed it
+  falls back to opening the GitHub **compare** URL (`POST /api/worktrees/pr`).
+
+Closing a worktree cell asks whether to **keep** the worktree or **discard & remove** it
+(a dirty worktree is never removed unless you confirm).
+
+**PRs & Issues (cross-repo).** The toolbar's **Pull requests** button opens a full-screen
+view that aggregates open PRs **and** issues across the repos listed in Settings →
+**Pull request repos** (`prRepos`, `owner/repo` entries) via your server-side `gh` login.
+PRs show a CI-rollup / review-decision / draft badge; each repo lists its latest open
+issues. Rows are real links, per-repo errors don't sink the view, and the two lists load
+independently. Backed by `GET /api/prs` and `GET /api/issues`.
+
+---
+
+## Cost & token usage
+
+Each grid cell's header shows two badges for its session, refreshed when a turn finishes
+(from `GET /api/session/:id`):
+
+- **Context badge** — e.g. `Opus · ctx 35%`: the model family plus how full its context
+  window is (the *last* turn's input + cache tokens ÷ the model's window — **1M** for
+  current-gen Opus / Sonnet / Fable, **200k** otherwise; an unknown model shows the label
+  with no %).
+- **Token badge** — `⇡<in> ⇣<out>`: cumulative input (fresh + cache-read + cache-creation)
+  and output tokens for the session, k/M-formatted, with a full breakdown in the tooltip.
+
+The **Settings** modal (⚙) shows an **estimated $ cost** — Session / Today / Month — from
+`GET /api/cost`, using a built-in public per-model price table (cache reads billed at
+0.1×, cache writes at 1.25× input). It's an estimate: real billing differs, **flat-plan
+(Max) usage isn't reflected**, and turns on unpriced models are flagged and excluded.
+
+A separate, full **double-entry accounting** book (the `account_balance` toolbar button →
+`/accounting`) is provided by the bundled `@mulmoclaude/accounting-plugin` and stores its
+books under `<workspace>/data/accounting`. It's a bookkeeping app — unrelated to the LLM
+cost estimate above — and is also exposed to Claude as the `manageAccounting` GUI tool.
+
+---
+
+## Wiki, Collections & the GUI panel
+
+MulmoTerminal is also a **live view over the shared workspace** (`CLAUDE_CWD`, default
+`~/mulmoclaude`) that agents author into — never a snapshot, so it re-reads on entry.
+
+**GUI panel.** Beside the terminal, a **GUI panel** ("Canvas") renders the rich results of
+GUI-protocol tools the agent calls — documents (`presentDocument`), forms (`presentForm`),
+generated images, charts, HTML, and collection cards. Each result is drawn by its plugin's
+own Vue view inside a Shadow-DOM `PluginFrame` (so a plugin's bundled CSS can't leak),
+mirrors the active session, and replays history on re-select. Plugins reach the agent over
+an **in-process MCP server** served per session at `POST /api/mcp/:sessionId` (server name
+`mulmoterminal-gui`) — which works from the host *or* the Docker sandbox (over
+`host.docker.internal`). Which plugins load is gated by `plugins/plugins.json`; the shipped
+set includes markdown, form, image generation (needs `GEMINI_API_KEY`), chart, HTML, and
+collection views. You can also merge your **own HTTP MCP servers** into the single-view
+session via Settings → `userMcpServers`.
+
+**Wiki.** The toolbar **Wiki** button opens a read-only browser over `<workspace>/data/wiki/`
+— an **index** (tag-filterable page catalog), rendered **pages** with `[[wiki links]]` and
+backlinks, a **graph** view (pages ranked by references), and a **lint** report (orphans /
+broken links / tag drift). Read-only endpoints: `GET /api/wiki`, `/api/wiki/graph`,
+`/api/wiki/lint`.
+
+**Collections.** The toolbar **Collections** button browses the workspace's collection
+"cards" (`@mulmoclaude/collection-plugin`). Running a collection **action** fetches a seed
+prompt and spawns a fresh agent session for it — the **Launch with Claude / Codex** toggle
+decides which agent (and whether the seed auto-runs or drops in as an editable draft).
+Favorited collections get their own toolbar buttons.
+
+---
+
+## More features
+
+- **Grid of parallel sessions** — the ＋ Terminal / grid view runs many sessions at once,
+  auto-sizing by count across pages. Cell borders signal state at a glance — **working**
+  (pulsing blue), **blocked** (amber — needs a permission / answer), **done** (blue —
+  finished, output unreviewed), and **idle** — and the toolbar shows a tally across all
+  pages so you notice an off-screen cell that needs you.
+- **Timeline** (🕘) — a read-only per-session activity timeline (tools run, newest first),
+  from `GET /api/transcript/timeline`.
+- **Tools pane** — the available GUI tools plus a live tool-call history for the active
+  session.
+- **Notifications** (🔔) — a toolbar bell with an unread badge and a dropdown of active
+  notifications; click a row to jump to its session.
+- **Voice input** — dictate a prompt via on-device Whisper (`POST /api/transcribe`, macOS
+  only; the model downloads on first use).
+- **Remote host** — link MulmoTerminal to the companion phone client (Google sign-in) to
+  watch and start sessions from your phone.
+- **Themes** — four terminal palettes (midnight / nord / daylight / solarized), your pick
+  remembered; a project's `.mulmoterminal.json` can override per directory.
+- **Editing niceties** — **Shift+Enter** inserts a newline in the prompt, and on macOS
+  **Option** is treated as Meta so Claude's Alt-key bindings work.
+
+---
+
 ## Server API specification
 
 Base URL: `http://localhost:$PORT` (default `http://localhost:34567`).
@@ -376,6 +628,33 @@ position the client sends back to `/ws/run`).
 A missing or invalid `script.json` is **not** an error — it yields an empty
 `scripts` array.
 
+### HTTP: `POST /api/command/summarize`
+
+Runs `claude -p` **headless** over a command cell's captured terminal output and
+returns a short summary (Errors / Warnings / likely cause / suggested fix). Backs the
+**✦ Summarize** button on a Run cell (see [Scripts (Run menu)](#scripts-run-menu)).
+The browser sends the cell's xterm buffer as `log`; the server truncates it to the
+last **32 KB** (the tail, where errors + the exit line live), runs the CLI with the
+log piped on stdin (argv — no shell), and returns its answer. Same-origin guarded.
+
+**Request `application/json`**:
+
+```jsonc
+{ "log": "npm ERR! cannot find module 'foo'\n..." }
+```
+
+**Response `200 application/json`**:
+
+```jsonc
+{
+  "summary": "Errors: cannot find module 'foo'\nSuggested fix: run `yarn add foo`",
+  "truncated": false // true when the log exceeded 32 KB and only the tail was analyzed
+}
+```
+
+Empty output returns a `{ summary }` note rather than calling the CLI. Errors:
+`400` (missing `log`), `403` (disallowed origin), `502` (the `claude` run failed).
+
 ### HTTP: `POST /api/hook`
 
 **Internal endpoint.** Claude hooks (injected per session — see
@@ -403,6 +682,62 @@ Any resulting state change is published on the `sessions` pub/sub channel.
 
 **Response `200 application/json`**: `{ "ok": true }` (always, even for unknown events).
 
+### More HTTP endpoints
+
+The endpoints above are the core; the server exposes many more (all under
+`http://localhost:$PORT`; query params shown where relevant). Mutating endpoints are
+same-origin-guarded.
+
+**Sessions & agents**
+
+| Endpoint | Purpose |
+| -------- | ------- |
+| `GET /api/session/:id?cwd=` | One session's summary — cumulative `usage` and `context` (model + last-turn context tokens). Backs the cell token & ctx% badges. |
+| `GET /api/codex/sessions?cwd=` | Codex sessions for the project (from `~/.codex` rollouts), newest first. |
+| `GET /api/cost?cwd=&session=` | Estimated $ cost — session / today / month. |
+| `GET /api/transcript/timeline?session=&cwd=` | Per-session activity timeline (tools run). |
+
+**Git & worktrees**
+
+| Endpoint | Purpose |
+| -------- | ------- |
+| `GET /api/git-status?cwd=` | `{ repo, branch, detached, dirty, ahead, behind, upstream }`. |
+| `POST /api/git-remote` | The dir's GitHub repo URL (for the header GitHub menu). |
+| `GET /api/worktrees?cwd=` · `GET /api/worktrees/diff?cwd=` | List managed worktrees / diff one vs its base. |
+| `POST /api/worktrees/create` · `/remove` · `/push` · `/pr` | Create on `agent/<slug>`, remove (managed root only), push, open a PR (`gh`, else compare URL). |
+| `GET /api/prs` · `GET /api/issues` | Open PRs / issues across the configured `prRepos` (via `gh`). |
+
+**Workspace views**
+
+| Endpoint | Purpose |
+| -------- | ------- |
+| `GET /api/wiki` (`?slug=`) · `/api/wiki/graph` · `/api/wiki/lint` | Read-only wiki index / page / graph / lint. |
+| `GET /api/collections/…` · `/api/feeds` · `GET\|PUT /api/shortcuts` | Collections browser, feeds, favorites (see `docs/collection-plugin-integration.md`). |
+| `GET /api/files/browse/{list,text,md}` · `PUT /api/files/browse/write` | File tree / read / Markdown-render / write (contained within the project root). |
+| `GET /api/files/raw?path=` | Raw asset bytes (workspace-rooted). |
+
+**GUI panel / plugins / MCP**
+
+| Endpoint | Purpose |
+| -------- | ------- |
+| `POST /api/mcp/:sessionId` | Per-session GUI MCP server (Streamable HTTP; `GET`/`DELETE` → 405). |
+| `POST /api/plugin/:toolName` | GUI-plugin dispatch (incl. `spawnBackgroundChat`, `manageAccounting`, `presentHtml`). |
+| `GET /api/agent/toolResults/:id` · `POST /api/agent/toolResult` | GUI-panel result history / persist. |
+| `GET /api/tools` · `GET /api/tool-calls/:id` | Available tools / tool-call history. |
+| `POST /api/accounting` | Double-entry accounting (bundled plugin). |
+
+**Config, sound & misc**
+
+| Endpoint | Purpose |
+| -------- | ------- |
+| `GET\|POST /api/config` | User UI config (`cwdPresets`, `soundFile`, `prRepos`, `launchers`, `userMcpServers`). |
+| `GET /api/sound` · `/api/dir-sound?cwd=` · `/api/dir-config?cwd=` | Custom / per-directory attention sound + per-dir config. |
+| `GET /api/notifications`(`/history`) · `POST /api/notifications/:id/clear` | Notification feed. |
+| `POST /api/transcribe`(`/model`…) | Voice-input transcription (Whisper, macOS). |
+| `POST /api/translation` | Runtime UI-string translation. |
+| `GET /api/remote-host/status` · `POST /api/remote-host/{connect,disconnect}` | Companion phone-client link. |
+| `POST /api/open-dir` · `POST /api/pick-file` | Reveal a dir in Finder/Explorer; OS file-picker → path. |
+
 ### WebSocket: `/ws` (terminal)
 
 A raw WebSocket carrying the terminal stream for one session. One PTY per
@@ -438,6 +773,20 @@ A non-JSON frame is written to the PTY verbatim (fallback).
 **kept alive** in the background; otherwise it's killed. See
 [Session lifecycle](#session-lifecycle).
 
+### More WebSocket endpoints
+
+Two more raw WebSockets share the `/ws` frame format (`output` / `input` / `resize` /
+`exit`):
+
+- **`/ws/codex?session=<id>&cwd=<dir>&gui=<0|1>`** — a **Codex** agent PTY (see
+  [Agents: Claude & Codex](#agents-claude--codex)). Like `/ws` it sends a `session` frame
+  with the id and reattaches to a live or tmux-backed session on resume. `gui=0` (grid
+  cells) omits the GUI MCP and keeps the session out of the sidebar.
+- **`/ws/launch?session=<id>&cwd=<dir>&launcher=<index>`** — a **launch command** PTY (a
+  plain shell, `codex`, or any command configured in Settings → Launch commands). Unlike a
+  Run-menu script it's **persistent and reattachable** (survives page switches /
+  reconnects), but it has no Claude hooks, so its dot only shows running vs. exited.
+
 ### WebSocket: `/ws/run` (command terminal)
 
 A raw WebSocket carrying a one-off **Run-menu command** (see
@@ -603,29 +952,44 @@ appears, at which point the on-disk title takes over.
 
 ```
 server/
-  index.js        Express app, /api routes, terminal WebSocket, PTY lifecycle,
-                  session state, hook injection, session discovery; also
-                  /api/scripts + the /ws/run command-terminal relay
-  scripts.ts      Loads/validates script.json; resolves a Run-menu command by index
-  pubsub.js       createPubSub(server) — socket.io pub/sub at /ws/pubsub
-  fix-pty-perms.js  postinstall: fixes node-pty prebuilt binary permissions
+  index.ts        Express app, /api routes, upgrade routing, PTY lifecycle,
+                  session state, hook injection, session discovery, GUI-MCP mount
+  agents/         AgentAdapter seam — claude.ts, codex.ts, registry.ts
+  codex-*.ts      Codex sessions, args, rollout discovery, skill mirroring
+  tmux.ts         tmux-backed session persistence (own -L mulmoterminal server)
+  sandbox.ts      Docker sandbox spawn for the single-view Claude session
+  worktrees.ts, worktree-*.ts   git worktree create/list/diff/push/PR + routes
+  git-status.ts, gitRemote.ts, gh.ts, prs.ts, issues.ts   git & GitHub (via gh)
+  cost.ts, transcript.ts        cost estimate; usage/context from transcripts
+  files-browse.ts               file tree + read/write (contained to project root)
+  scripts.ts                    Run-menu script.json loader
+  command-summary.ts            POST /api/command/summarize (claude -p headless)
+  app-config.ts, config-routes.ts, dir-config.ts   user + per-directory config
+  plugins-registry.ts, mcp/     GUI plugin registry + per-session MCP broker
+  backends/                     wiki, collections, feeds, accounting, notifier,
+                                translation, whisper, remote-host, html, files
+  pubsub.ts                     socket.io pub/sub at /ws/pubsub
+  fix-pty-perms.js              postinstall: fixes node-pty binary permissions
 src/
-  App.vue         Layout (sidebar + terminal); owns the active session id
+  App.vue                       Layout; owns the active session + single/grid view
+  router/                       Vue Router routes (/, /terminals, /collections,
+                                /accounting, /prs, /files, /wiki, …)
   components/
-    Sidebar.vue       Session list; working dot + waiting bold; pub/sub driven
-    Sidebar.spec.ts   Vitest component tests
-    Terminal.vue      xterm.js terminal; /ws (or /ws/run); single-view ▶ Run menu
-    AppToolbar.vue    Shared header (single + grid); grid-only ＋ Terminal + ⇅/↔ cell-order toggle
-    GridView.vue      Grid view: auto-layout, pages, manual/auto cell order; runs handed-off scripts
-    RunMenu.vue       ▶ Run dropdown: lists a dir's script.json, emits the pick
-    TerminalCell.vue  A cell: Claude launcher (dir picker + resume + run-a-script); ◀▶ to reorder
-    TerminalGrid.vue  Grid of cells; auto-sizes by count; zoom lines up every tab
-    CommandCell.vue   A grid cell that runs a script.json command (ephemeral)
-  composables/
-    usePubSub.ts      socket.io-client pub/sub composable (subscribe/unsubscribe)
-    usePendingScript.ts  Hands a header-picked script to the grid to run
-    useUnloadGuard.ts  Confirm before closing/reloading the tab while a terminal is live
-vite.config.ts    Dev proxy for /ws (covers /ws/run), /ws/pubsub, /api
+    Sidebar.vue, SessionTabBar.vue           session list + tab bar (pub/sub driven)
+    Terminal.vue                             xterm.js terminal; /ws, /ws/codex, /ws/run
+    AppToolbar.vue                           shared header + toolbar buttons
+    GridView.vue, TerminalGrid.vue, TerminalCell.vue, CommandCell.vue, LauncherCell.vue
+    GuiPanel.vue, PluginFrame.vue            GUI panel (Canvas) + Shadow-DOM plugin host
+    FilesOverlay.vue                         file browser + CodeMirror editor
+    GitBranchChip.vue, ModelContextBadge.vue header chips / badges
+    PrsOverlay.vue                           cross-repo PRs & Issues
+    Wiki*View.vue, Collections*.vue, AccountingOverlay.vue   workspace views
+    TimelineOverlay.vue, ToolsPane.vue, NotificationBell.vue, RemoteHostControl.vue
+    SettingsModal.vue                        ⚙ settings
+  composables/                  useSessions, usePubSub, useGitStatus, useCost,
+                                useChatLauncher, useFilesView, useWikiBrowse,
+                                useCollectionBrowse, useNotifications, useVoiceInput, …
+vite.config.ts    Dev proxy for /ws (+ /ws/codex, /ws/launch, /ws/run), /ws/pubsub, /api, /artifacts
 vitest.config.ts  jsdom test environment
 ```
 

package/dist/assets/{abnfDiagram-VRR7QNED-6nNByj6v-BR__eiyl.js → abnfDiagram-VRR7QNED-6nNByj6v-Ce1WbMGC.js}

@@ -1 +1 @@
-import{n as e}from"./chunk-Y2CYZVJY-Bdt8pFDJ-DsF7k-Jl.js";import{f as t}from"./src-Brzfja-q-ch1VcTiG.js";import{_ as n,g as r}from"./mermaid-parser.core-DC7NPJ_M-ylD2dn6D.js";import"./chunk-WYO6CB5R-B83L_z6I-DmI80qCd.js";import"./chunk-VAUOI2AC-DrcykVNK-Bx9_R8iV.js";import{n as i,r as a,t as o}from"./chunk-MOJQB5TN-CqxshQHA-o-9QjKwX.js";import{t as s}from"./chunk-JWPE2WC7-BQ3zXr2k-DSd3Ct95.js";var c=r().RailroadAbnf.parser.LangiumParser,l=e(e=>{let t=e.alternatives.map(u);return t.length===1?t[0]:{type:`choice`,alternatives:t}},`transformAlternation`),u=e(e=>{let t=e.elements.map(f);return t.length===1?t[0]:{type:`sequence`,elements:t}},`transformConcatenation`),d=e(e=>{if(e.includes(`*`)){let[t,n]=e.split(`*`);return{min:t?parseInt(t,10):0,max:n?parseInt(n,10):1/0}}let t=parseInt(e,10);return{min:t,max:t}},`parseRepeat`),f=e(e=>{let t=p(e.primary);if(!e.repeat)return t;let{min:n,max:r}=d(e.repeat);return n===0&&r===1?{type:`optional`,element:t}:{type:`repetition`,element:t,min:n,max:r}},`transformElement`),p=e(e=>{switch(e.$type){case`AbnfStringLiteral`:return{type:`terminal`,value:e.value};case`AbnfNumVal`:return{type:`terminal`,value:e.value};case`AbnfRuleName`:return{type:`nonterminal`,name:e.name};case`AbnfGroup`:return l(e.element);case`AbnfOptionalGroup`:return{type:`optional`,element:l(e.element)};default:throw Error(`Unsupported ABNF primary node: ${e.$type}`)}},`transformPrimary`),m=e(e=>({name:e.name,definition:l(e.definition)}),`transformRule`),h=e(e=>{s(e,a),e.title&&a.setTitle(e.title),e.rules.map(e=>a.addRule(m(e)))},`populateDb`),g={parser:{parse:e(e=>{a.clear(),t.debug(`[ABNF Parser] Starting Langium parse`);let r=c.parse(e);if(r.lexerErrors.length>0||r.parserErrors.length>0)throw new n(r);let i=r.value;t.debug(`[ABNF Parser] Parsed rules:`,i.rules.length),h(i),t.debug(`[ABNF Parser] Parse complete`)},`parse`),parser:{yy:a}},db:a,renderer:o,styles:i};export{g as diagram};
+import{n as e}from"./chunk-Y2CYZVJY-Bdt8pFDJ-DsF7k-Jl.js";import{f as t}from"./src-Brzfja-q-ch1VcTiG.js";import{_ as n,g as r}from"./mermaid-parser.core-DC7NPJ_M-YbqcHI8U.js";import"./chunk-WYO6CB5R-B83L_z6I-D-ILEUuT.js";import"./chunk-VAUOI2AC-DrcykVNK-DNVpp2Bo.js";import{n as i,r as a,t as o}from"./chunk-MOJQB5TN-CqxshQHA-C1do_qle.js";import{t as s}from"./chunk-JWPE2WC7-BQ3zXr2k-DSd3Ct95.js";var c=r().RailroadAbnf.parser.LangiumParser,l=e(e=>{let t=e.alternatives.map(u);return t.length===1?t[0]:{type:`choice`,alternatives:t}},`transformAlternation`),u=e(e=>{let t=e.elements.map(f);return t.length===1?t[0]:{type:`sequence`,elements:t}},`transformConcatenation`),d=e(e=>{if(e.includes(`*`)){let[t,n]=e.split(`*`);return{min:t?parseInt(t,10):0,max:n?parseInt(n,10):1/0}}let t=parseInt(e,10);return{min:t,max:t}},`parseRepeat`),f=e(e=>{let t=p(e.primary);if(!e.repeat)return t;let{min:n,max:r}=d(e.repeat);return n===0&&r===1?{type:`optional`,element:t}:{type:`repetition`,element:t,min:n,max:r}},`transformElement`),p=e(e=>{switch(e.$type){case`AbnfStringLiteral`:return{type:`terminal`,value:e.value};case`AbnfNumVal`:return{type:`terminal`,value:e.value};case`AbnfRuleName`:return{type:`nonterminal`,name:e.name};case`AbnfGroup`:return l(e.element);case`AbnfOptionalGroup`:return{type:`optional`,element:l(e.element)};default:throw Error(`Unsupported ABNF primary node: ${e.$type}`)}},`transformPrimary`),m=e(e=>({name:e.name,definition:l(e.definition)}),`transformRule`),h=e(e=>{s(e,a),e.title&&a.setTitle(e.title),e.rules.map(e=>a.addRule(m(e)))},`populateDb`),g={parser:{parse:e(e=>{a.clear(),t.debug(`[ABNF Parser] Starting Langium parse`);let r=c.parse(e);if(r.lexerErrors.length>0||r.parserErrors.length>0)throw new n(r);let i=r.value;t.debug(`[ABNF Parser] Parsed rules:`,i.rules.length),h(i),t.debug(`[ABNF Parser] Parse complete`)},`parse`),parser:{yy:a}},db:a,renderer:o,styles:i};export{g as diagram};

package/dist/assets/architecture-TIHT7OUA-CYMWc3UT-CkMBxcjf.js

@@ -0,0 +1 @@
+import{f as e}from"./mermaid-parser.core-DC7NPJ_M-YbqcHI8U.js";export{e as createArchitectureServices};