4.0.0 — the grid is the app
A snapshot of 4.0.0 as released on 2026-08-01. It will go out of date as the app moves on; that is fine and expected. For the reference that is kept current, follow the links to the living guide in each section.
Two things are removed in this release. That is what makes it a major, and it is the only part of this page you have to read: the single terminal view and the Docker sandbox. Nothing you configured stops working, and there is nothing to migrate — but if you bookmarked /chat, or if you had MULMOTERMINAL_SANDBOX set, read the first two sections.
Everything else here is new behaviour you get by upgrading.
1. The single view is gone. Where did everything go?
Until 3.x there were two screens, switched with the chat / grid icons: the grid for supervising many agents, and a single view at /chat for focusing on one. The single view is deleted.
Focusing on one agent is now zooming its cell — it takes the window, and the GUI panel (Canvas) opens beside it. That is the same arrangement the single view had.
| What you did before | What you do now |
|---|---|
Open /chat to focus on one agent | Zoom that cell (the expand button in its header) |
| Read the Canvas on the right | It is beside the zoomed cell |
| Pick a session from the sidebar | The cockpit roster beside the zoomed cell; for sessions not on the grid, an empty cell’s OR RESUME HERE list |
| Open Collections / Wiki / Accounting / Files | The Collections button in the toolbar — the others appear once you are inside |
| Settings | Same button, same place |
/chat still works in the sense that it does not error. It is now an unknown URL, and unknown URLs land on the grid.
The Collections door
The content surfaces used to be reachable only from the single view. They now have one button of their own, sitting beside Grid in the toolbar as a peer of the views:
- Click Collections (the grid-of-squares icon, immediately right of the Grid icon).
- Feeds, Wiki, Accounting and Files appear in the row once you are inside.
- Closing any of them returns you to the view you opened it from.
Pull requests and Worklog stay with the terminals — they are work under supervision, not content — so they are in the toolbar while the grid is on screen, where they always were.
→ Basics: the toolbar · Features
2. If you ever set MULMOTERMINAL_SANDBOX
The Docker sandbox is removed. MULMOTERMINAL_SANDBOX, MULMOTERMINAL_SANDBOX_IMAGE, SANDBOX_MOUNT_CONFIGS and SANDBOX_SSH_AGENT_FORWARD no longer do anything.
You do not have to edit your .env. A stale key is ignored rather than an error, and the session runs on the host — which is what it already did whenever Docker was unavailable.
If you ever turned it on, this version cleans up after it once at startup: the ~/.mulmoterminal/sandbox directory (which held an exported Keychain credential per session) and any mulmoterminal-<id> container still running with your workspace mounted. If you never turned it on, nothing runs — not even a docker call.
It was opt-in, macOS-only, and only ever wrapped the single-view session. Keeping it would have meant porting it to the grid, which is the opposite of what it was for: it existed to contain one interactive session, and the grid runs many.
3. A worktree runs one agent session
Nothing to configure — this is how the launcher behaves from now on.
A worktree is tied to a branch, so a second agent in it is not isolation: it is two agents editing one working tree. Each worktree row in an empty cell’s launcher is now one of three things:
| The row says | What clicking it does |
|---|---|
| nothing extra | starts the worktree’s first session |
resume | continues the session it already has |
in use (amber, not clickable) | nothing — that session is open in another terminal |
The limit follows the directory, not the row. Pasting the same worktree path into WORKING DIRECTORY, or reaching it from a recent-dir chip, is refused the same way — and the refusal is enforced by the server, so a path spelled another way (a trailing slash, a symlink) does not get past it either.
It applies to agents: Claude, Codex, Antigravity, and an OR LAUNCH command that runs one of them. A Shell, and a launcher running anything else (yarn dev, lazygit, htop), is still free to open there — a worktree an agent is working in is exactly where you want those.
What to do when a row says in use
Close the session where it is open, and the row becomes resume. “Where it is open” now includes another browser tab and a second mulmoterminal running on this machine — the server answers that question from its own process table plus tmux, rather than from what one page can see.
This replaces a confirmation. The resume list used to let you click past ● open and take a session over, which detached whoever had it — including you, in the other window, mid-turn.
→ Basics: the launcher form · Git worktrees
4. Google Calendar collections actually sync
If you have a collection with a googleCalendar block, check it after upgrading — it may start doing something it never did on this host.
MulmoTerminal never registered the calendar sync task, so neither the pull nor autoPush ran. Anyone also running MulmoClaude on the same workspace had it done for them by that host, which is what made this hard to notice: it worked for people running both, and silently did nothing for MulmoTerminal alone.
Nothing to turn on. If the collection is configured, the task is now registered and runs on its schedule.
5. Smaller things you will notice
- A cell tells you its PR merged, and the button opens the same keep / remove confirmation that was always there. Worktree cells only; no default action; the × dismisses it for that PR.
- A chat started from the Collection UI opens with that collection already on the Canvas, and its prompt now appears immediately rather than after about ten seconds.
- A session started from the phone appears on the grid straight away, without needing you to navigate away and back.
- A scheduled task’s chat is a background worker: behind the Background filter, never bold, and it no longer takes a grid cell per firing. A failed one shows as
● failed, and Web Push still fires for it. - Background workers are findable in an empty cell’s session list, labelled
background.
Nothing else changes
No config key was renamed, no CLI flag moved, and every directory setting, theme, keymap and launcher you already had keeps working.
← Guide index · 3.0.0