MulmoTerminal

Run multiple Claude Code and Codex sessions in parallel — and see which one needs you.

A browser terminal for parallel AI coding agents: several Claude Code and Codex sessions side by side, each in its own cell, with the one that needs you marked in colour. Vibe coding with a single agent needs nothing but a shell — this is for when you run several and lose track of which is waiting. Sessions survive a reload (tmux), work isolates in git worktrees, and a phone push reaches you when a turn finishes.

Every cell is a real pty. htop, lazygit, a dev server and Claude Code are the same kind of object here — which is why the one-session-per-worktree limit applies to agents only, and a shell or a yarn dev launcher can sit in the same worktree an agent is working in.

📖 Documentation — receptron.github.io/mulmoterminal

• User guide: English — the grid view, everyday workflows, the full feature list, configuration, and mobile push notifications.
• ユーザーガイド: 日本語 — グリッドの使い方・日々のワークフロー・機能一覧・設定・スマホ通知の設定はこちら。
• Updates / アップデート情報: new releases and features are announced in Japanese on X — 新バージョンや新機能のお知らせは X の Singularity Society (@SingularitySoci) で。

Demo

https://github.com/user-attachments/assets/0b8dd582-6c0d-4be3-b0b4-3740ad0bdba6

90 seconds, with sound — one agent, then a grid of them, each cell coloured working, done or needs you. Zoom into one and the roster still holds what every other session asked, answered and did, so you go to whichever is lit and lose nothing catching up. Then the same grid, live:

MulmoTerminal turns Claude Code (and OpenAI's Codex) into a parallel, observable workspace: many agent sessions at once in a grid, each one color-coded so you see at a glance which are working, which need you, and which are done — plus rich GUI output, git worktrees with one-click PRs, cost readouts, and a ping to your phone when a task finishes. One npx command, no Electron, no config.

npx mulmoterminal@latest        # starts on http://localhost:34567 and opens your browser

Built by receptron — Satoshi Nakajima, software architect for Windows 95 at Microsoft, and Isamu Arimoto; the same two behind GraphAI. More ↓

Something looks wrong? Type /mulmoterminal-bug-report in any MulmoTerminal session. The bundled skill hears the symptom out, checks your real config, schema and version to see whether the behaviour is configuration or by design, searches the existing issues — and only helps you file one if none of that explains it, with the environment collected and secrets masked. Getting you unstuck is the goal; an issue is what is left when the first three steps fail.

*The grid is a cockpit for parallel agents — here, four live Claude sessions, each in its own color-coded project. Every cell's header carries what you need to triage at a glance: model · context %, token counts (⇡in ⇣out), the git branch / changes chip, and an AI summary of what the agent is doing. A cell's border color signals state — working (blue), done (green), needs-you (amber — e.g. waiting on a permission), idle — with an attention chime so a stuck cell off-screen still pulls you back. Supervise many; only step in where you're called.*

Why you'll want it

• See every agent at once. A grid of live sessions, each cell color-coded by state — working (blue), blocked / needs a permission (amber), done, unreviewed (blue), idle — with an attention chime and a toolbar tally, so an off-screen agent that's stuck never slips past you. Stop babysitting one terminal; supervise ten. Zoom into one and the cockpit roster keeps everyone else in view — one text row per session with its AI summary, last prompt, latest reply, and the branch's PR phase (draft / CI fail / ready / merged).
• A GUI for your agents, not just a terminal. Beside the terminal, a Canvas panel renders what an agent produces over MCP — documents, forms, charts, generated images, HTML, collection cards — each drawn by its own plugin. The agent doesn't just print text; it hands you an interface.
• Get pulled back from anywhere. A finished — or input-waiting — task sends a Web Push to your phone, and the RemoteHost companion lets you watch sessions and answer with a 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.
• 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.
• Know what it's costing. Per-session context %, token, and estimated $ readouts, an activity timeline of tool calls, and AI-summarized cell titles and command-output explanations — so a wall of parallel agents stays legible.
• Make it yours. Per-directory themes, colors, and name badges (prod in red, staging in amber), a configurable header (buttons + info chips), custom attention sounds, and Run / Skill menus to launch a project's scripts and .claude/skills right inside a cell.

Zoomed in, the cockpit roster replaces thumbnails with information: every session as a text row — directory, AI summary, your last prompt, the agent's latest reply, a status word, and the branch's PR phase badge. A row whose agent is waiting on you rings amber and blinks; one that has merely finished rings green and stays still (Settings → Waiting rows turns the movement off). Click a row to swap the enlarged terminal.

What it is, under the hood

Each session runs as a real PTY on the server (the agent CLI in a pseudo-terminal) and is streamed to an xterm.js terminal in the browser over a WebSocket. The cockpit roster lists every session and reflects, in real time, which are working (the agent is thinking, a spinner), which are waiting on you (a permission prompt or a question — an amber dot; nothing proceeds until you answer) and which are finished with output you haven't seen (a green dot) — driven by Claude/Codex activity hooks the server injects per spawn. The horizontal tab bar carries the same two dots.

To focus on one agent, zoom its cell: it takes the window, and the GUI panel ("Canvas") opens beside it, where that agent's tool calls render as documents, forms, charts, images, and HTML rather than printed text. The app opens on the grid (/, settling on /terminals), which is the only view; 3.x had a separate single view at /chat and 4.0.0 removed it, so that URL now lands on the grid like any other.

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, or click the file button in the terminal header, which asks the local server to open the OS file dialog and inserts the chosen path. The path is inserted at the cursor — it is not submitted, so you can review it first.

A drag inserts the file's own path where the browser exposes one via file:// (Firefox/Safari), so editing it afterwards edits the file you dropped. Where the browser withholds it — Chrome, and every browser when MulmoTerminal is open from another machine, where a local path would name nothing on the host — the file's bytes are sent instead, saved to a private per-session directory under the OS temp dir, and that path is inserted. The session is granted that directory at launch (Claude Code's --add-dir), so the agent reads it without a permission prompt; the copies are removed when the session ends, and any left by a crash are swept at the next start. Up to 110 MiB per file — the same ceiling as a phone attachment. A session already running when you upgrade was launched without that grant, so drops into it still prompt; new sessions don't.

Pasting a screenshot — take a screenshot and paste it straight into the terminal (Cmd/Ctrl+V). The image is saved to the session's own drop directory — the same place a dropped file goes, with the same grant, the same 110 MiB ceiling and the same cleanup when the session ends — and its absolute path is inserted at the cursor, so the agent can read it. Unlike a drop, this does not need the browser to expose a path — the bytes are on the clipboard — so it also covers Chrome, where dropping a file cannot insert a path. It works wherever the browser puts the image on the clipboard as image/png, image/jpeg, image/gif, or image/webp. Anything else is left to the terminal's own paste handling, exactly as before — including a paste that carries plain text next to the image, which copying from a web page usually does, so that pasting text keeps working.

Clicking a file path — the other direction. A path an agent prints becomes a link, and what it opens is chosen by its extension, so each kind arrives as the thing it is rather than as bytes (files within the session's working directory only):

While a grid cell is enlarged, the Files pane takes the click first — every row above except the last one, since the pane is the same editor plus a Markdown preview. The file opens beside the terminal that printed it, and the pane opens itself if it was closed. It declines, leaving the routing above untouched, when nothing is enlarged, when the path is not under that cell's own directory (the pane cannot walk above its root), or for the raw-bytes row, where it would only show an empty editor.

Highlighting in the Files view covers the JS/TS family, JSON and Markdown (the modes cmEditor.ts bundles); other languages open as plain text.

This set is deliberately asymmetric with the set the server serves as viewable text — .md goes to the rendered viewer rather than the Files view, .txt does the opposite, and dotfiles are server-only. The 45 extensions both sides agree on live in common/sourceExtensions.ts, each side adds its own extras, and test/common/sourceExtensions.spec.ts pins the asymmetry so it isn't "fixed" into symmetry.

Changing this? The routing table is ROUTE_BY_EXTENSION / IN_APP_EXTENSIONS in src/composables/terminalFilePathLinkProvider.ts. Update this section, the docs/guide/{en,ja}/features.md row, and the link table in docs/terminal-notes.md together — all three went stale once already (#834).

What people say after switching

These are experiences reported by users who moved over from an IDE or a split terminal — not benchmarks, and not claims we measured. Your setup may differ.

"It stopped eating my memory"

Keeping several agents apart by opening several IDE windows is expensive: each one brings its own editor, language server, extensions and file watchers. One user reported a 64 GB machine stuttering under that load, and running smoothly after moving over — here the agents are PTYs on a server and the UI is browser tabs.

"I stopped answering the wrong agent"

Six panes of scrolling text look identical. Users have described typing a reply into another agent's terminal, and losing track of what they had asked in the first place. As one put it, the windows all look the same, so switching between them costs time just to work out what you are looking at.

The problem isn't attention — it's that N identical panes means holding N contexts in your head. Colour-coded state, a name badge and a per-directory colour move that onto the screen instead.

"Watching many and reading one stopped being a trade-off"

Splitting a terminal six ways leaves every pane too small to read a long answer without constant scrolling and resizing — one user described exactly that with a 4,000-character reply. So you quietly accept worse reading every time you add an agent.

Grid ↔ enlarge removes that. Watch all of them, then blow one up and read it properly — the cockpit roster keeps the rest in view as text while you do.

"My existing sessions came with me"

Sessions resume as-is — same claude --resume, same transcripts. Point it at a directory you already work in and your history is there. Nothing to migrate, nothing to redo. One user said this alone made the switch worth it, having previously lost context to killed sessions.

You don't need ten agents for this to pay off. Users have reported the switch being worth it at one to three parallel sessions. The wins above are about not losing track, not about running more.

Install & run

Needs Node ≥ 22.9, plus these CLIs on your PATH:

Never installed any of this before? The guide walks it end to end, macOS and Windows, assuming no command-line experience: Getting started · はじめに — 起動するまで

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 these it can find.

npx mulmoterminal@latest           # start on http://localhost:34567 and open the browser
# or install globally:
npm install -g mulmoterminal
mulmoterminal

Stopping it. Ctrl+C in the terminal that started it — or, if you can no longer find that terminal, Settings → Quit MulmoTerminal in the browser, or npx mulmoterminal@latest stop from any terminal (installed globally, just mulmoterminal stop). All three run the same shutdown: with tmux installed the agent sessions survive and come back under Settings → Sessions that survived a restart; without it they end with the server.

First-run setup (optional). npx mulmoterminal@latest init checks your environment (Node ≥ 22.9 and every CLI in the table above), seeds the launcher's directory presets from the projects in your Claude Code history, and writes ~/.mulmoterminal/config.json. It's idempotent — re-run it any time to refresh the presets; it overwrites the managed parts and keeps your other settings. When claude is installed it can hand off to the /mulmoterminal-config skill for interactive tweaks — it routes to the one that owns what you want to change. Once the app is up you can also reach them from Settings: each section that a skill can write ends in a button that starts that skill in a new session, which is how the settings with no UI (a theme of your own, keymap) get written without hand-editing JSON.

Google account (optional). Link a Google account to enable the chat's google tool and the phone's google.calendar.* commands: read/create events on any calendar (not just your primary), list the calendars you've subscribed to, and read the colour palettes. Sign in from Settings → Google account, or run npx mulmoterminal@latest google login — the CLI is the fallback for when you're driving MulmoTerminal from another machine, since consent finishes on a loopback listener and needs a browser on the host. Either way it needs a Desktop OAuth client JSON saved as ~/.secrets/client_secret_*.json; the refresh token lands in ~/.config/mulmo/google-token.json and is shared with MulmoClaude, so one link per machine covers both apps.

Local models (optional). The package also ships claude-ollama — a one-command launcher that runs Claude Code fully locally against an Ollama model (no cloud, no API key). It starts a large-context Ollama server and launches claude with a minimal system prompt so small models aren't drowned:

ollama pull qwen3:4b
npx -p mulmoterminal claude-ollama qwen3:4b   # or, if installed globally: claude-ollama qwen3:4b

See Local models with claude-ollama for the details and model notes.

Already linked before the calendar-list / colour features? They need a read scope your existing link doesn't have, so listCalendars (and, in practice, colors) fail with an insufficient-scope 403 until you re-authorize: Settings → Google account → Unlink, then sign in again (or re-run google login). Reading/creating events on your primary calendar keeps working without re-linking.

A global install isn't auto-updated, so on startup MulmoTerminal checks npm and prints a one-line notice when a newer version is available — and the web toolbar shows a clickable update badge with the exact command for your install (npm i -g mulmoterminal, or git pull for a clone). The server repeats that check every few hours, so a release that ships while it is running still reaches the badge; the startup console notice is printed once and is not repeated. Disable with MULMOTERMINAL_NO_UPDATE_CHECK=1 (or NO_UPDATE_NOTIFIER=1).

Options: --cwd <dir> (working directory — relative paths allowed; defaults to the directory you run the command from), --port <n> (default 34567), --no-open, --version, --help.

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 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. The launcher detects it and prints the exact, OS-appropriate removal command; run that, then npx mulmoterminal@latest again.

Contents

• Architecture
• Why a PTY?
• Agents: Claude & Codex
• Session persistence (tmux)
• Tech stack
• Configuration
• Running
• Scripts (Run menu)
• Skills (Skill menu)
• Files view (browse & edit)
• Git worktrees & pull requests
• Cost & token usage
• Wiki, Collections & the GUI panel
• More features
• Server API specification
  • HTTP: GET /api/sessions
  • HTTP: GET /api/scripts
  • HTTP: POST /api/command/summarize
  • HTTP: POST /api/hook
  • More HTTP endpoints
  • WebSocket: /ws (terminal)
  • More WebSocket endpoints
  • WebSocket: /ws/run (command terminal)
  • Socket.IO: /ws/pubsub (activity pub/sub)
• Session model
• Session lifecycle
• Claude hook injection
• Closing summary
• Session discovery & titles
• Project structure
• Testing
• Contributing

Architecture

┌──────────────────────────────────────┐         ┌─────────────────────────────────────────────┐
│ Browser (Vue 3 + xterm.js)            │         │ Server (Express + Node)                       │
│                                       │         │                                               │
│  App.vue ──────subscribe("sessions")──┼──SIO───►│  socket.io  /ws/pubsub   ── publish ──┐       │
│      ▲  refetch on any push (favicon) │         │                                       │       │
│      └──── GET /api/sessions ─────────┼──HTTP──►│  Express   /api/sessions              │       │
│                                       │         │            /api/hook  ◄──curl── hooks │       │
│  Terminal.vue ── ws JSON msgs ────────┼──WS────►│  ws        /ws  ──► node-pty ─► `claude`──hooks┘
│      (input / resize / output)        │         │                     (one PTY per session)     │
└──────────────────────────────────────┘         └─────────────────────────────────────────────┘

• Terminal I/O flows over a raw WebSocket (/ws), one PTY per session.
• Session list is fetched over HTTP (/api/sessions) — by App.vue for the tab favicon, and by an empty cell's launch form (?cwd=) for its resume rows.
• 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.
• 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 and Scripts (Run menu).
• In dev (yarn dev) the Vite dev server runs on its own port (CLIENT_PORT, default 6856) and proxies /ws (a prefix covering /ws/codex, /ws/launch, and /ws/run), /ws/pubsub, /api, /artifacts, and /htmlfile 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.

Why a PTY?

Claude Code's interactive mode renders its UI with Ink (a React-based TUI framework), which requires a real TTY to be attached. A plain child_process.spawn() provides no TTY, so interactive Claude won't start (it stays silent). node-pty allocates a real pseudo-terminal at the OS level, so from Claude's point of view it's running in an ordinary terminal — full TUI rendering, cursor movement, colors, and tool-approval prompts all work. We don't use -p/headless mode or the Agent SDK; we drive the real interactive CLI and relay its TTY over the WebSocket.

macOS note: node-pty's bundled spawn-helper binary ships without the execute bit (mode 644), which causes a posix_spawnp failed error. The postinstall script (server/fix-pty-perms.js) fixes it to 755 automatically.

Agents: Claude, Codex, Antigravity & Grok

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. Four adapters ship today — Claude Code (the default), Codex, Antigravity (agy), and Grok.

• 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 per spawn (see Claude hook injection) plus the closing summary instruction. The whole GUI MCP (--mcp-config, on one all-tools URL) goes only to a session that is not a grid cell, or to a grid cell whose cwd IS the workspace — claimFullGuiMcp in server/session/registry.ts, which is what gives a workspace cell the tools the single view had before 4.0.0 removed it. That equivalence is about what the session carries: a workspace cell is still a grid cell in every other respect. A cell in a project directory attaches none of ours, so its GUI tools come from whichever Canvas switches are registered for it. Either way, Claude Code loads your own MCP servers normally — the directory's local scope, any .mcp.json up the tree, your global ones and your claude.ai connectors. It did not always: --strict-mcp-config used to ride along with --mcp-config, which hid all of that from the very sessions meant to be the most capable (#1338, #1385).

• 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 cockpit roster 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". That mapping is appended to ~/.mulmoterminal/codex-rollouts.jsonl, so a conversation is still resumable after the server restarts — without it a session whose tmux is also gone came back as a fresh codex. Resume reattaches a live PTY, adopts a surviving tmux session, or cold-resumes the rollout id.

• Antigravity — spawned as agy (override with ANTIGRAVITY_BIN; ANTIGRAVITY_MODEL sets --model). Antigravity runs on its own WebSocket (/ws/antigravity). Like Codex it mints its own conversation id, so the server watches ~/.gemini/antigravity-cli/brain/ (home overridable via ANTIGRAVITY_HOME) for the directory the new conversation creates — attributed only when unambiguous — and cold-resumes it with --conversation <id>. That mapping is appended to ~/.mulmoterminal/antigravity-conversations.jsonl, so a conversation is still resumable after the server restarts — the same log Codex keeps, in the same format.

  Its GUI tools work differently — in the workspace too, because agy takes no MCP flag: it reads its servers from .agents/mcp_config.json in the working directory. So it never gets the workspace's "every tool automatically"; register what it needs with the Canvas switches, wherever it runs (see MCP server ids). MulmoTerminal writes that file from the directory's Canvas switches — the same switches Claude's cells read — so one switch serves every agent, and rewrites it whenever a switch flips or an agy session starts. Servers in it that MulmoTerminal did not write are left alone, the file is removed once no group is on, and it is kept out of your git status through .git/info/exclude — a local switch on a local machine, so it never reaches a diff or your team. The entry runs server/mcp/bridge.mjs, a stdio-to-HTTP shim onto the same in-process GUI MCP server the other agents call. The session id is never written into that file — it is per directory and shared by every session running there — and reaches the bridge through the agy process's own environment instead.

• Grok — spawned as grok (override with GROK_BIN; GROK_MODEL sets --model), on its own WebSocket (/ws/grok). It resumes the way Claude does rather than the way Codex and Antigravity do: grok --session-id <uuid> starts a conversation under an id MulmoTerminal minted, so there is no watcher, no attribution guess, and no mapping log — the id the browser holds is grok's own. A reconnect passes --resume <id> instead, but only once a conversation by that name exists on disk: grok writes one under ~/.grok/sessions/<url-encoded cwd>/<id>/ (home overridable via GROK_HOME) after the first turn, and re-using a --session-id that already exists is a hard error, which is why the two flags are never sent together.

  Its GUI tools work like Antigravity's — in the workspace too and for the same reason: grok takes no MCP flag, so it never gets the workspace's "every tool automatically" either, and MulmoTerminal registers the bridge in .grok/config.toml (grok's project-scope config) from the directory's Canvas switches, wherever it runs (see MCP server ids). That file is TOML and yours, so — unlike agy's JSON — MulmoTerminal never rewrites it directly: it drives grok mcp add -s project / grok mcp remove -s project, and only for the server ids it wrote itself. Nothing else in the file is touched, a directory already in the right state runs no command at all, and the file is added to .git/info/exclude only when MulmoTerminal created it. As with agy, the session id is never written into that file — it reaches the bridge through the grok process's own environment.

Choosing an agent. Each grid cell's launch form carries the Agent Picker — a Claude / Codex / Antigravity / Grok / Shell toggle — and the Collections browser a Claude / Codex / Antigravity / Grok one (your choice is remembered). Shell is not an agent: it runs your OS default shell ($SHELL, or /bin/sh) in the chosen directory, with nothing to install and nothing to configure. It starts a launcher cell, so it has no model, no MCP registration, and no worktree — those rows disappear while it is picked.

Other models. Claude Code can run against any Anthropic-compatible backend (OpenRouter, Moonshot, a LiteLLM gateway). Backends are listed in ~/.mulmoterminal/config.json under providers, and their keys are read from the server's environment — never from a file the app serves. A directory sets its default in .mulmoterminal.json (provider / model), and each grid cell's launch form has a MODEL select that overrides it for one session, listing ~27 curated models with the measured pass rate of a real tool-using task beside each. A provider whose token can't be resolved refuses to start rather than falling back to Anthropic. Full walkthrough — setup, the measured model list, adding your own models, troubleshooting: Using another model via OpenRouter.

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 a tmux session, so a server crash or restart doesn't kill your terminals — the processes keep running and reattach when the server comes back (like screen/tmux). A long build, a dev server, or a mid-turn Claude session all survive node --watch reloads and crashes. It uses its own tmux server (-L mulmoterminal) and config, so it never touches your personal tmux sessions or keybindings.

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.

Installing tmux (optional):

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.

Tech stack

Requires Node ≥ 22.9 (uses node --env-file-if-exists) and the claude CLI on PATH.

Configuration

The server is configured entirely through environment variables, optionally loaded from a .env file. npx mulmoterminal@latest reads the .env in the directory you run it from; the npm scripts read the one in the repo root. The .env is optional — every variable below has a default, so the server runs without one.

A variable already set in your shell wins over the same name in .env, so adding a file never overrides what you exported. The server's environment is inherited by every terminal it starts, so anything in .env is also visible to the claude / codex sessions themselves.

The update-check opt-outs (MULMOTERMINAL_NO_UPDATE_CHECK, NO_UPDATE_NOTIFIER) are covered in Install & run.

Example .env (gitignored):

CLAUDE_CWD=/Users/you/my-project

UI settings (~/.mulmoterminal/config.json)

The Settings modal (the gear button) persists per-user UI choices to ~/.mulmoterminal/config.json (read/written via GET/POST /api/config):

Open it from the gear button in the toolbar. The sidebar groups the sections — Appearance, Projects, Header & launch, Input, Models & servers, Notifications, Integrations, Sessions, Help — and one is on screen at a time; on a phone the sidebar becomes a picker above the section. Settings is available in English and Japanese: it follows your browser's language unless you pick one under Language (per browser, like the theme). Only this modal is translated so far. Under the title, a Version row shows what is running: the version from the shipped package.json, plus a commit <sha> chip on a git checkout — there the version is only whatever was last released, so the commit is what identifies the build. When something newer exists, the row is followed by the header badge's update notice, command included. Pick a theme, set the terminal font size, font and scroll speed (and whether sending returns to the latest output), set a custom attention sound, list the repos the cross-repo PRs & Issues view should aggregate, add launch commands for grid cells, register your own MCP servers, and turn on the switches for what this app writes on your behalf — issue work comments, the PR clone footer, the closing summary, the decision digest, the dev worklog — no need to hand-edit the config file. Four settings stay with their skill because a form would be the wrong tool for them (keymap, themes, providers, buttons/chips); Settings shows what each is doing now and launches that skill. Note that theme, font size, scroll speed and the return-to-latest switch are stored per browser (they're display preferences, so a phone and a desktop keep their own); the rest live in ~/.mulmoterminal/config.json and are shared by every client.

Every MulmoTerminal on the machine shares this one file, so an older build could save over a key a newer one wrote. It doesn't: a top-level key this version doesn't recognise is written back untouched, which is what makes running two versions side by side — or downgrading for a while — safe. A mistyped key survives on the same rule, which is deliberate: a line you can still see is easier to debug than one that silently vanished. See the Configuration guide.

Header buttons

Each terminal header shows configurable action buttons. Omitting buttons (globally or per-dir) keeps the built-in starter set: a file-path picker (📎), an OS file-manager reveal (📂), an in-app file explorer (📁), a new terminal here (🖥), this branch's PR (🔗, git repos, only when a PR exists), and open-on-GitHub (🌐, git repos). Setting buttons (at either level) replaces the whole default set with your list (it is not merged on top), so listing your own — even a shorter one — is how you drop, reorder, or swap them. A button has an id, label, and a run of "shell" (run a command), "input" (send text to the agent), or "open". An open button targets one of url / reveal (OS file manager) / files (in-app explorer) / view (a built-in overlay) / terminal (a dir → a new cell running $SHELL, opened next to the current one) / pr: true (open the current branch's PR — the button is hidden when there's no open PR) / pickFile: true (OS file dialog → insert the path). ${dir}, ${branch}, ${repo}, … substitute live context, and when (e.g. "isGitRepo") gates visibility. The /mulmoterminal-header skill writes a valid config interactively; per-dir buttons merge over the global ones by id, while chips replace the global list wholesale.

Notification sounds

Six moments can beep, each with its own sound and its own on/off switch. Running many agents at once is what turns notifications into noise, so only the first two are on by default — the rest are opt-in from Settings.

A Run cell is the one-shot cell a script.json entry or a run:"shell" header button opens — not a shell launcher cell. A launcher runs an interactive shell that stays alive, so nothing marks where one command inside it ended; only the one-shot cell reports an exit code.

finished and waiting reach the phone too (pushKinds); the other four are seen only in the browser — a Run PTY never enters the session registry, and a PR phase is something the page polls — so Web Push cannot raise them.

What each one plays. 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 concerns. Beyond it there are two options:

• Presets — seven sounds hosted in the ownplate repo (MIT), referenced as preset:<id>: chime coin cheep door gong magic meow. The first play downloads one into ~/.mulmoterminal/sounds/; every later play reads that file, so a preset keeps working offline. A failed download is not remembered as one — you get the chime that time and the next play retries. That holds on both sides: the server caches no failure, and it answers 503 (not 404) for a preset it could not fetch, because the browser remembers a 404 for the life of the page and only retries a 5xx.
• Your own file — an absolute path, per kind in sounds or as the all-kind soundFile.

Resolution per kind, nearest first: the session directory's sounds[kind], its sound, your sounds[kind], your soundFile, then the chime. The server streams whichever applies at GET /api/sound?kind= / GET /api/dir-sound?cwd=&kind=, and the client falls back to the chime if it's missing or not audio.

Web Push on task finish. Enable pushEnabled in Settings to have the server send a push (title = the project dir, body = the last prompt) to your registered devices each time a background task finishes — the same signal as the attention chime, but for the panes you're not watching. Delivery is handled by the separate mulmoserver sendPush Cloud Function; MulmoTerminal only makes the call, and only while the RemoteHost channel is connected (its Google sign-in supplies the notification auth). With RemoteHost disconnected, or with no device registered, the toggle is a no-op.

Dev worklog (cross-clone). Set worklogEnabled: true in ~/.mulmoterminal/config.json (and restart — the scheduler reads its tasks at boot) to register a built-in scheduled task. Every worklogIntervalHours (default 6) it spawns a Claude session that reviews the work you did across all your saved working dirs (cwdPresets) since it last ran, and writes it up as a short manager-style report. It runs as a background worker: behind the Background filter, never bold, and it takes no grid cell, so an hourly task cannot fill the grid. Web Push still fires for it — being quiet means out of the way, not unreachable, and it runs while you are away. Multiple clones/worktrees of the same repo (e.g. myapp, myapp2) are merged into one per-repository section, each covering what problem was addressed, what got solved, what's still in progress, and — mined from the transcripts — decisions that were only discussed and not built. The window is since the last run (tracked in config/scheduler/worklog-state.json), not a fixed 6 h, so a missed/slept run doesn't drop work. It reads and reconciles progress against vision.md / milestones.md (creating empty ones if absent) so a long-running goal isn't forgotten.

A run due while the server was off is not lost: built-in scheduled tasks record their runs in config/scheduler/state.json and catch up at startup, each by its own missed-run policy. The worklog's is run-once — a single run covering everything since the last, so several missed windows don't become several batches summarising the same period. Whether they ran, and when they run next, is in GET /api/scheduler/tasks; the history is in GET /api/scheduler/logs (?taskId=&since=&limit=, newest first) and on disk under data/scheduler/logs/.

Output lands in the wiki: one weekly page per ISO week (data/wiki/pages/dev-log-YYYY-www.md — filenames are lowercase, or the wiki can't open them), each tagged worklog. To browse them, open the 作業ログ 一覧 hub page (worklog), which links every week, or click the #worklog tag in the wiki index.

Off by default because each run costs tokens — watch the cost readout and tune the cadence. Run it on a single "hub" instance; running it in several instances sharing one workspace double-fires it. The batch treats everything it reads (transcripts, git, wiki) as untrusted data and only writes the worklog / hub / vision / milestones pages.

Per-directory settings (<project>/.mulmoterminal.json)

Drop a .mulmoterminal.json in a project directory to give terminals opened in that directory their own look and sound. It applies per terminal (per grid cell) — the rest of the app keeps your chosen theme — and a directory's theme overrides your manual theme pick for that terminal only. Every field is optional; a missing or malformed file is ignored.

{
  "name": "PROD · payments",            // badge shown on this directory's terminals
  "icon": "docs/logo.png",              // image on this dir's cells (path here, URL, or data:); omit to use the repo's favicon
  "badgeColor": "#cf222e",              // badge color (hex #rrggbb)
  "headerColor": "#190a23",             // cell header background (hex #rrggbb)
  "headerTextColor": "#ffffff",         // cell header text color while idle (hex #rrggbb)
  "headerStatusColors": {               // what the header shows once a status takes the background over
    "working": "#6d28d9",               //   just the background — the text colour is derived from it
    "done": { "background": "#166534" },
    "blocked": { "background": "#7c2d12", "text": "#ffe8a3" }
  },
  "headerStatusTint": "background",     // "none" keeps headerColor while working/done (not blocked)
  "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
  "fontSize": 16,                       // terminal font size in px (8–32); overrides Settings
  "fontFamily": "'Cica', monospace",    // terminal font stack; overrides the global config
  "orderPriority": 10,                  // rank in the grid's "priority" order and the launcher chips (lowest first)
  "sound": "./.mulmoterminal/alert.mp3", // attention sound, RELATIVE to this directory
  "sounds": { "command-failed": "preset:gong" }, // per-notification-kind override
  "appendSystemPrompt": false,          // no closing summary here; omit to follow the global setting
  "worktreeEnv": {                      // a port / database name of its own per git worktree
    "PORT": { "kind": "port", "base": 3000 },
    "DB_NAME": { "kind": "slug", "prefix": "myapp_" }
  }
}

Already have a repo.json? MulmoTerminal reads it. It is an open repository-metadata format — one small file any tool can read — and a project that ships one gets a coloured, named, icon-bearing cell without knowing this app exists:

{ "name": "diffusion-lab", "icon": "docs/logo.png", "color": "#7c3aed" }

One colour becomes all seven: the header is it exactly, the badge/border/dot/button/body are derived from its hue, and the header text is derived for contrast. Anything this app understands but the open format doesn't goes under extensions.mulmoterminal.

The three files layer, general to specific — repo.json → .mulmoterminal.json → .mulmoterminal.local.json — replacing whatever keys the one below it set.

Several clones of one repository? Drop a .mulmoterminal.local.json beside it. It is read after .mulmoterminal.json and replaces whatever keys it names, so the shared file holds what the project is — name, theme, a colour — and each checkout's local file holds only what makes it recognisable:

// .mulmoterminal.json — the project. Complete on its own, so one clone needs nothing else.
{ "name": "acme-web", "theme": "nord", "badgeColor": "#1b3479", "headerColor": "#2d4ea9", "orderPriority": 30 }

// .mulmoterminal.local.json — this checkout only. Gitignore it.
{ "badgeColor": "#27b4a8", "headerColor": "#4ed0c5", "orderPriority": 65 }

Whole keys, not a deep merge: a colors block in the local file replaces the shared one entirely. Settings → Directory settings names both files and lists which keys the local one took over.

As cells pile up it gets hard to tell which project is which. Give each repo a name badge and its own colors in .mulmoterminal.json and they're unmistakable — headerColor/badgeColor tint the frame, while colors reaches all the way into the terminal's own background and text. (The example above dresses four repos in Mondrian / van Gogh / Picasso / Matisse palettes.)

Security. sound and every sounds entry are directory-relative paths only — absolute paths and any ../ that escapes the directory are rejected, and the path is never taken from the HTTP request, so an opened project can't point the player at arbitrary files. When changes take effect. A write made through Claude's tools — which includes the mulmoterminal-dirs skill — applies live: the tool hook that reports the write doubles as the reload signal, so colors, palette, font size and grid order update without reopening anything. There is no filesystem watcher, so an edit made outside a session (your own editor) is picked up when the terminal is next opened.

Checking what took effect. Settings → Directory settings lists your recent directories and expands each one to the values in force, with a swatch per color and the path of the file they came from. It also names the keys it dropped (a color that isn't #rrggbb, a size out of range) and the keys it doesn't read at all (badgeColour, a global-only setting) — which is what tells "I never set that" apart from "I set it and it didn't take".

Running

yarn install            # postinstall fixes node-pty prebuilt binary perms

yarn dev                # backend (:34567) + Vite UI (:6856), concurrently — open http://localhost:6856
# or individually:
yarn dev:server         # backend only  (node --import tsx --env-file-if-exists=.env server/index.ts)
yarn dev:client         # Vite dev server only

yarn typecheck          # type-check everything (vue-tsc -b)
yarn build              # type-check + vite build -> dist/
yarn server             # run backend; serves dist/ + the APIs on :34567
yarn test               # vitest run

yarn typecheck covers the whole repo. The root tsconfig.json is a solution file that references all five projects, so one vue-tsc -b builds them: tsconfig.app.json (client), tsconfig.node.json (vite config), tsconfig.server.json (backend, run directly via tsx with no build step), plus tsconfig.test.json and tsconfig.test-server.json for the specs — which need checking of their own because vitest strips types rather than checking them. They exist as separate projects because each has its own compiler options (the client ones DOM + .vue, the server ones node, the specs with noUncheckedIndexedAccess off).

In dev, open the Vite URL; its proxy forwards /ws, /ws/pubsub, and /api to :34567, plus the two mounts that serve a presentHtml page to the Canvas iframe, /artifacts and /htmlfile — a page path missing from that list is answered by Vite's SPA catch-all with index.html, which renders as a blank iframe rather than an error. In production, run yarn build then yarn server and open http://localhost:34567.

Scripts (Run menu)

An empty grid cell's launcher sets the Working directory by typing, by a preset chip, or with the 📁 folder button (a native OS folder dialog). The preset chips are the directories you have launched in — worktrees excluded, since one is a single task's branch that is deleted with the task, not a place to launch in again; the workspace leads them always, labelled WORKSPACE and marked with an icon, whether or not you have ever launched there — it is the one directory where a claude or codex session reaches every GUI tool (agy and grok get what the directory registered, there as anywhere — see MCP server ids), so it is never a click you can lose. It has no remove button for the same reason. It is named for its role rather than its folder, because the folder name (~/mulmoclaude by default, or wherever CLAUDE_CWD points) says the least interesting true thing about it; the real path is on its hover.

The launcher is shorter in the workspace, because two of its choices do not apply there. The per-directory Canvas switches are replaced by a line saying every GUI tool is already available — a session there is handed the whole GUI MCP at spawn, so a switch would register a group URL that then has nothing left to serve. With Antigravity or Grok picked they stay, in the workspace as everywhere else: neither is handed anything at spawn and both read their servers from the directory's file, so the switches are their only route to a GUI tool and hiding them would leave the session with none (see MCP server ids). And the worktree section is hidden: a worktree isolates work on one codebase onto a branch, while the workspace is what a session works from (the shared wiki, collections and accounting live there), which is precisely what a detached branch would cut it off from. Both come back the moment you point the field at a project directory.

It also offers a run a script row that launches project scripts (a dev server, tests, a build, …) in that cell, in the directory the cell is pointed at — so a whole workflow lives in one window alongside the Claude sessions. Scripts are per-directory: the cell reads the script.json of whatever directory you select, so different cells can offer different projects' scripts.

The same launcher also has an or launch row for your configured launch commands — any interactive command — set in Settings (the gear button) → Launch commands as { label, command } (e.g. htop → htop, Codex → codex). A plain shell needs no entry here: the Agent Picker's Shell option already opens $SHELL. Unlike a one-shot script, a launcher runs as a persistent terminal in the cell's directory: it survives grid page switches and reconnects, and its dot shows running vs. exited (it has no Claude hooks, so no blocked/done states).

Every running terminal's header also has a ▶ Run ▾ dropdown (next to the connection status) — but only when the open project has scripts (no script.json, no button). It lists the open project's script.json — the directory that terminal runs in — and launches the picked script in a spare grid cell (reusing an open launcher, else a new one), so you can watch it. So you can start a dev server or tests for the project you're working in without disturbing the session that's running.

The list is populated from a script.json at the chosen directory's root. It's optional; a directory without one simply shows no scripts.

// <dir>/script.json
{
  "scripts": [
    { "label": "Dev server", "command": "yarn dev" },
    { "label": "Unit tests", "command": "yarn test" },
    { "label": "Build", "command": "yarn build" },
    // optional per-script working dir (relative to this file, or absolute):
    { "label": "Sub server", "command": "yarn serve", "cwd": "packages/server" }
  ]
}

A command terminal is not a Claude session: it has no session id, no hooks, no transcript, and isn't persisted — it's ephemeral, so a page reload drops it and closing the cell (or reloading) kills the process. When the command exits, the cell offers a ↻ re-run. The browser only ever sends the script's index + its 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.

Skills (Skill menu)

Next to the ▶ Run ▾ dropdown, every running terminal's header has a ⚡ Skill ▾ dropdown — and only when the open project has skills (nothing discovered, no button). It lists the Claude skills discoverable for that terminal's directory — both project scope (<dir>/.claude/skills) and user scope (~/.claude/skills), the same skills Claude sees — and, on pick, runs the skill in that session: it types the skill's invocation into the terminal and submits it (for Claude, its /<slug> command; for Codex, which has no slash command, a plain Use the "<slug>" skill. instruction). Unlike ▶ Run — which launches a script.json shell command in a spare cell — a skill runs in the session you picked it from, continuing that conversation.

Ordering: working-dir (project) skills come first, then user-scope ones, alphabetical within each group; a project skill of the same slug shadows the user one.

Filtering: add a skills array to the directory's .mulmoterminal.json to narrow the menu — an allowlist of slugs that also sets the order (only those show, in that order). Omit it to show everything.

// <dir>/.mulmoterminal.json
{ "skills": ["review-diff", "commit-msg"] }

Each menu item shows the skill's id, with its SKILL.md description as the hover tooltip. A directory (or workspace) without any .claude/skills simply shows no button. Skills are discovered read-only; the menu never creates or edits them.

Files view (browse & edit)

A terminal header can carry a 📁 Files button — add it as a header button ("open": { "files": "${dir}" }) — that opens a full-screen file explorer rooted at that terminal's project directory — so after Claude says "wrote foo.md" you can jump straight there to read or edit it. The left pane is a lazy-loaded directory tree; clicking a file opens it in a CodeMirror editor (Markdown / JS-TS / JSON highlighting, everything else as plain text). Markdown files get a Preview toggle that renders via the server's sandboxed …/md HTML. Save (or ⌘/Ctrl-S) writes back.

Beside an enlarged terminal, not only full-screen. Expand a grid cell (⤢) and its header gains a folder toggle that splits the enlarged area in two: terminal on the left, the same explorer + editor on the right, rooted at that cell's directory. Drag the divider (or focus it and use ←/→, Home, End) to resize — the terminal keeps a floor, so a squeeze shrinks the pane rather than reflowing xterm into garbage. It works in both zoomed layouts (cockpit roster and thumbnail filmstrip), the pane re-roots as you walk the zoom between terminals, and whether it's open plus how wide it is are remembered per browser.

The toggle is not the only way in: while a cell is enlarged, clicking a file path the agent printed opens it here too, rather than in a new tab or full-screen — see Clicking a file path.

All reads and writes go through GET/PUT /api/files/browse/*?cwd=&path=, and every path is contained within the project root (server-side) — ../absolute escapes are rejected for reads and writes alike, so editing can't reach outside the directory the terminal is pointed at. A save sends the version the file had when it was opened, so it is refused (409) rather than silently overwriting an agent that edited the same file meanwhile; the editor then offers to reload or to overwrite deliberately.

You usually hear about it before that. An open file that changes on disk is picked up from Claude's own write hook (immediately) and from a 30-second version check (which catches Codex, git, builds and other editors too). A clean buffer just takes the new content — the pane reads as a live view — while a dirty one raises the same banner rather than choosing for you.

Leaving an open file saves it — switching files, moving the enlargement to another terminal, closing the pane, navigating away. No dialog interrupts you mid-flow, because opening a file, and replacing one, keep a copy under ~/.mulmoterminal/backups/ — three generations per file, outside the project so they never reach git status or the agent's view of its own repo. A parting save that loses the version race banks your version there instead of overwriting the other writer. Re-opening unchanged content doesn't rotate one in, and a backup that can't be written never blocks the read or the save it was taken for.

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 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 below the field.

A worktree inherits the project's settings. A fresh worktree used to have none — no colours, no name, no model, no grid rank. It is now given its own copy derived from the project's, written to .mulmoterminal.local.json so it layers over whatever the repository committed: name / theme / colors / fontSize / fontFamily / provider / model / worktreeEnv as written (the last is a declaration rather than a value — the worktree resolves its own values from it), the seven chrome colours rotated 12 degrees further around the hue wheel per worktree (so a project's trees read as a gradient; a grey like #ffffff has no hue to move and stays put), and orderPriority at the project's rank + 1, so the worktree sorts directly after it. sound / sounds / addDirs are not carried — they name paths inside the project directory. Written only where git would ignore what it writes: an untracked file in a worktree's git status would make it count as dirty, and a dirty worktree is one MulmoTerminal refuses to remove. The local override is preferred; a repo that ignores .mulmoterminal.json instead (the setup this feature shipped with) still gets its colours there. A committed shared config is never written to. A local file the worktree already has is never overwritten.

One worktree, one session. A worktree is tied to a branch, so it is never started twice: a listed row resumes that worktree's session when it has one, and starts one only when it has none. A row whose session is open in another terminal reads in use and cannot be clicked — close it there first. The refusal follows the directory, not the row: the same worktree reached by pasting its path into WORKING DIRECTORY, or by a recent-dir chip, will not launch either — and the server refuses the spawn whichever client asks, so a path spelled another way (a trailing slash, a symlink) does not slip past.

What the limit covers is an agent: Claude, Codex, Antigravity or Grok, including an OR LAUNCH command that runs one of them. A Shell, and a launcher that runs anything else (yarn dev, lazygit, htop), stays free — a worktree an agent is working in is exactly where you want those. A project that declares worktreeEnv also gets its own value per worktree for each variable it declares there — so two dev servers given a port of their own do not both reach for 3000 (see worktreeEnv).

The same holds for OR RESUME HERE: a session someone is holding is listed with ● open and refused, where before it could be confirmed away — which detached whoever had it. "Someone" means any terminal anywhere, including another browser tab and a second mulmoterminal process on this machine: the server answers from its own PTY table plus tmux, not from what one page can see.

Change the directory and those lists empty immediately, replaced by a single Loading this directory's sessions, worktrees and scripts… row until the new ones arrive. Everything the launch form offers below the field — OR RESUME HERE, the worktrees and OR RUN A SCRIPT — belongs to the directory it was read for, and reading it costs a debounce plus a round trip. Rows left standing through that wait would be the previous directory's, listed under the new directory's name, and clicking one resumes exactly the session it offers.

A worktree started from an issue gets an issue/<N>-<slug> branch instead. The number in the name is what later tells the app which issue the work belongs to: the ⧉ Open PR button puts Fixes #<N> in the PR body, and the branch chip, the issue work comment and the merge-time auto-close all read the same number rather than guessing at it.

That path also fetches first and forks from origin/<base>, because several clones of one repo often run side by side and only the one being worked in gets pulled — forking from the local branch would start the work on however old that clone happens to be. A local base that already contains the remote wins anyway (it is a superset, so nothing is lost), and with no remote reachable the local branch is used and the worktree is still created. Typing a task name yourself keeps the local base it has always used, with no fetch.

Every empty grid cell shows this launch form: pick an agent in the Agent Picker (Claude / Codex / Antigravity / Grok / Shell), type a working directory (frequent ones autocomplete from your presets), or — in a git repo — name a task under OR ISOLATE IN A WORKTREE and hit ＋ New worktree to start the agent on its own isolated branch. Shell runs your OS default shell there instead of an agent; OR LAUNCH runs one of your configured launch commands.

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, or gitlab.com/group/project — plus any host declared in gitlabHosts) via your server-side gh / glab 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.

Starting work from an issue row. Each issue row carries a ▶ button that does the setup in one click: read the issue, cut an issue/<number>-<slug> worktree in your clone of that repo, and open Claude there as a grid cell with the issue typed into its input box but not sent. The prompt is seeded server-side as a draft (server/session/draft-injection.ts), which waits for claude's input box to be ready — text pushed in before that lands in the scrollback instead. A repo with several clones asks which one the first time and remembers the answer; a repo with no clone here disables the button and says why. Backed by POST /api/issues/start.

Which clone a repo's work happens in. GET /api/repo-dirs answers the reverse of the GitHub link a cell already shows: given owner/repo, which of your saved directories are clones of it. The candidates are derived from your directory presets by reading each one's origin — there is no second list to keep in step — and are ordered by each directory's orderPriority, then by path. Several clones of one repo commonly run side by side, so the answer is a choice rather than a lookup; once you make it, repoDirs in the config records owner/repo → the chosen path and it is used from then on. A recording is dropped if the directory is no longer a saved clone of that repo, and a repo with no clone here is simply absent from the answer — which is how a caller learns work cannot start on it.

Cost & token usage

Each grid cell's header shows two badges for its session, refreshed when a turn finishes (from GET /api/session/:id):

Both badges, live on a real Claude session: Sonnet · ctx 9% (model family + how full its context window is) and ⇡1.8M ⇣6.9k (cumulative input / output tokens for the session). They sit in the header's first row alongside the status dot and the git chip (⎇ main ●2), with what the agent is doing to the right; the working directory, the icon buttons and the timeline (🕘) of tool calls are on the second row.

• 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 / Mythos, 200k otherwise). A session running on a provider model shows that model's name and its published window (Kimi K2.7 Code · ctx 12%); a model in neither list keeps the label and hides the %, since the window is never guessed. A reading past 100% shows ctx ? instead of the number: the window is a hard cap, so an impossible percentage means the built-in window table is out of date for that model rather than that the session is over-full.
• 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.

Both badges are read from the agent's own log, so what each agent can show differs by what it writes down (?agent= on the route picks the reader):

The token badge hides itself when nothing has been counted, and the context badge shows the model alone unless it has both a current-context token count from the agent and a context window — agent-reported (codex, Grok, Antigravity) or resolved from the built-in table above (Claude, provider models). Either one missing means a name and no percentage. The two badges are independent: an Antigravity session whose accounting cannot be read still shows its model, and one whose cumulative totals are zero still shows a percentage. The context badge is absent entirely until an agent has named a model: codex and Antigravity file their logs under an id the agent mints after the session starts, so a brand-new cell shows no model badge until it has been prompted once — a few seconds, not the rest of the session.

Antigravity's numbers are the one case read from a store with no published format: agy keeps its per-generation accounting as protobuf in ~/.gemini/antigravity-cli/conversations/<id>.db, with no schema on disk, so the fields are identified by measurement (see server/agents/antigravity-usage.ts). Every layer of that reader is built to answer nothing rather than a number it is unsure of, so if a future agy release moves those fields, an Antigravity cell falls back to showing its model alone — it will not show a wrong percentage.

The Settings modal (the gear button) 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. Which plugins load is gated by plugins/plugins.json; the shipped set includes markdown, form, image generation (needs GEMINI_API_KEY), chart, HTML, collection, and mulmoscript (MulmoCast video/slides/PDF playback) views. You can also merge your own HTTP MCP servers into a workspace session via Settings → userMcpServers.

MCP server ids: why a workspace cell and a project cell disagree

A tool is never called by its own name. Every MCP client prefixes it with the id of the server it came from — mcp__<id>__presentChart in Claude Code, mcp-<id>-presentChart in Codex (which also rewrites - in the id to _). So the id you register under is repeated on every tool, in every listing, for the life of the session.

MulmoTerminal delivers the GUI MCP by three different routes, and they do not share an id:

The third is Muse, which reads neither a flag nor a file in the directory: its MCP servers are declared by an installed plugin, and muse plugins install records one per MACHINE. So MulmoTerminal registers a single mulmoterminal plugin holding all four group servers, and each session is narrowed back to what its own directory switched on — the bridge asks the server which session it belongs to (by its process tree) and is told which groups that session may reach. The servers are named by group alone, because Muse composes the tool name out of both ids:

Muse's plugin support is behind its own experimental flag (MUSE_EXPERIMENTAL_PLUGINS), which MulmoTerminal sets on the sessions it starts. A Muse build without it simply has no GUI tools — the registration fails with one warning and the session starts anyway.

A Muse session picks its plugins up when its own process starts, and MulmoTerminal's sessions outlive the server. So a Muse cell that was already running when you switched a group on — or when you first upgraded to a version that has this — keeps no tools until that CELL is started again. Restarting the server is not enough: the session is still there in tmux and gets reattached, exactly as it was. Close the cell and open a new one (or Stop it in Settings → Surviving sessions), and it comes back with the tools its directory registered.

Which route a session takes is decided by carriesFullGuiMcp() in server/session/mcp-config.ts — the single view, a cell-less chat, or anything whose cwd is the workspace take the first; anything in a project directory takes the second.

The workspace is agent-agnostic for the agents that can RECEIVE a per-spawn config — claude and codex ask the same predicate, so two terminals in the workspace reach the same tools no matter which of the two started them. Antigravity, Grok and Muse cannot, and that is the exception you will meet first:

None of the three takes an MCP flag: agy reads .agents/mcp_config.json, grok reads .grok/config.toml in the working directory, and muse reads a plugin installed for the whole machine — and neither a file shared by every session in a directory nor a machine-wide plugin can be handed to one session and not another — so there is nothing for "this cwd is the workspace" to change. The membership is FULL_GUI_MCP_AGENTS in common/guiMcpAgents.ts, in common/ precisely so the launcher form and the spawn cannot disagree about it (#1423).

The consequence is easy to hit and hard to guess: presentDocument works in a project you once flipped Canvas on for, and is missing in the workspace where everything else is automatic. Fix it the same way anywhere — pick Antigravity or Grok, point WORKING DIRECTORY at that directory, flip the Canvas switch (it stays visible for both), and start a new session; the switch registers the directory, never a session already running. Full procedure: Antigravity and Grok register everywhere · 日本語.

A launcher chip is not an agent session — it is a command. Whatever the command line names, it runs exactly as written: nothing is inserted, and no GUI MCP is attached. A chip running claude therefore reads only its directory's own .mcp.json, and a chip running codex has no Canvas. If you want a chip to reach the GUI tools, put the flags in the command yourself.

Earlier releases did rewrite a claude or codex chip to match the cell beside it. That was removed: a chip that silently runs something other than what it says is indistinguishable from the Agent Picker, which is the confusion the two controls exist on either side of. Use the Agent Picker for an agent session — it is also the only one of the two that gives you a resumable transcript, cost and context, and a "waiting for you" status.

The asymmetry is deliberate. mt is ours to name: nothing on disk holds it, it is regenerated on every spawn, so it was shortened to stop paying 17 characters per tool name. The group ids are the opposite — they are keys in config files users wrote, they are what the launcher's per-group switch reads back, and they are documented in the setup guide. Renaming them breaks working setups silently, and would need a migration that rewrites existing per-folder configs. Both live in common/toolGroups.ts, where the constants carry the same warning.

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) whose [[links]] are clickable too. 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.
• Zoom & filmstrip — a cell's ⤢ enlarges one agent while the rest shrink to thumbnails in a bottom filmstrip; click a thumbnail to switch, ⤡ to return to the grid — so you can flip between "see everything" and "focus on one" in a click. While zoomed, keys you bind walk the enlargement along the on-screen order without reaching for the mouse — opt-in, nothing is bound by default, since any bound key is taken from the terminal underneath. Add a keymap to ~/.mulmoterminal/config.json; see the guide for the syntax, the action list, and combinations a browser can never bind.

• Set a terminal aside — the moon button in a cell's header sinks it: the tile, its filmstrip thumbnail and its cockpit-roster row all fade, and the working dot stops pulsing. The session stays connected and keeps its whole history — this is what to reach for instead of /clear-ing a cell you are done with for now, which resets the conversation just to change how the cell looks. The setting survives a reload. Enlarging it keeps it faded — that is how you read a set-aside session without waking it, and its roster row keeps the blue "you are here" edge either way — while typing into it wakes it, so nothing has to be undone by hand. Clicking or scrolling to read it does not wake it, even though a mouse-tracking agent receives those as input. A cell that stops for a permission prompt comes back to full strength on its own, so setting one aside can never hide a session that is waiting on you; a merely finished turn does not, since that is the expected outcome of setting a running agent aside.
• Timeline (🕘) — a read-only per-session activity timeline (tools run, newest first), from GET /api/transcript/timeline.
• Bring another cell's turn here (💬) — pick another terminal in the grid and its last completed turn is pasted into this cell's input box, so you can have Claude and Codex look at each other's work (or pull in a session running in a different repo). The excerpt comes from the agent's own log, not the screen buffer, so it carries no ANSI debris and nothing lost to scrollback. It is pasted, never sent — you read what arrived and press Enter, in the cell you were already in. A turn still running isn't available yet (Codex writes its rollout only once the turn ends).
• Tools pane — the available GUI tools plus a live tool-call history for the active session.
• Prompts pane — the prompts you sent the enlarged cell's session, newest first, from GET /api/transcript/prompts. The mirror of the Timeline above: that one is what the agent ran, this one is what you asked it for — for when several cells are running and you can no longer remember which one you told what. Read-only; click a long prompt to open it in place. Left open, it keeps up by itself. Claude and Codex; it reads what you TYPED (claude's own prompt history, codex's rollout), so a prompt sent mid-turn is there and text a skill injected is not. A /clear draws a line: the pane shows what you have asked since, the same way the header, the title and the last reply all stop describing the ended conversation.
• Notifications (🔔) — a toolbar bell with an unread badge and a dropdown of active notifications; click a row to jump to its session.
• Star MulmoTerminal — a star button in the grid toolbar that stars the project on GitHub through your own gh login, in one click. It is a one-time ask: once the repo is starred the button is gone for good and stops calling the server at all. It shows only when gh can answer — with no gh, no login, or no network, one click couldn't star anything, so nothing is shown and nothing is recorded. Set gh up later and the button appears by itself.
• Voice input — dictate a prompt via on-device Whisper (POST /api/transcribe, macOS only; the model downloads on first use). Settings picks the language you dictate in (per browser): your browser's, whisper's own per-clip detection, or a fixed one. Worth setting — speech in a language the mic is not expecting comes back translated into the one it is, so an English browser silently turned Japanese dictation into English.
• 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. If your Claude Code is rebound so Enter and Shift+Enter behave backwards, flip them with terminalSubmit.
• Scroll speed — one wheel notch or trackpad swipe moves the terminal the same distance whether you're reading a shell's scrollback or a full-screen app like Claude Code. If a two-finger scroll on a Mac trackpad flies past what you were reading, turn terminal scroll speed down in Settings (0.25×–3×, per browser — it's a property of the pointing device).
• No accidental page zoom — Ctrl+wheel and a trackpad pinch would rescale the whole page and drag the layout and the terminal's fit along with it, so both are ignored. Keyboard zoom (Cmd/Ctrl + / -) still works when you mean it, and a phone's finger pinch is untouched. To make terminal text bigger for real, use the font size in Settings (or a directory's fontSize) — that re-fits the PTY instead of leaving it disagreeing.

Server API specification

Base URL: http://localhost:$PORT (default http://localhost:34567).

HTTP: GET /api/sessions

Lists the most-recent chat sessions for the current project (CLAUDE_CWD), newest first, including freshly-created sessions that aren't yet written to disk.

Response 200 application/json

{
  "cwd": "/Users/you/my-project",
  "sessions": [
    {
      "id": "d16f43f3-ef63-4a5e-b273-debaccb3522a", // session UUID (= .jsonl basename)
      "title": "Review available skills list",        // see "Session discovery & titles"
      "mtime": 1781471064511.22,                       // last-modified, ms epoch (sort key)
      "working": false,                                // Claude is mid-turn (blue dot)
      "waiting": false                                 // needs attention (bold)
    }
    // ...
  ]
}

• Sessions are read from ~/.claude/projects/<encoded CLAUDE_CWD>/*.jsonl and merged with in-memory sessions started this run but not yet persisted (those have title: "New session" and mtime = creation time).
• Sorted by mtime descending and capped at the 50 most recent. Files are ranked by a cheap stat-only pass; only the top 50 are read and parsed for titles, so the endpoint stays cheap regardless of how many sessions exist.
• 500 { "error": string } on an unexpected filesystem error. A missing project directory is not an error — it yields an empty sessions array.

Directories that cannot be used

Every ?cwd= — on the terminal sockets and on the read routes alike — names the directory the request is about. When one is named and cannot be used, the server says so instead of quietly answering about the default workspace (#1151):

…