Muse Code · 6 min read

Attach to running sessions and co-drive them from the CLI

Muse Code 1.4.15 lets a second terminal attach to a running session, several clients co-drive it, and the command line send it messages. The same week adds per-session hosts, custom subagent definitions, MCP management from the CLI and richer SDKs.

Key takeaways 6
  • `muse sessions --json` lists the sessions running on your machine, and `muse attach <session-ref>` opens your terminal as a second driver on the same timeline.
  • Several clients can co-drive one session on a shared host. Submissions run one at a time in order, and `muse attach --stdio` and `muse serve --per-session` give each session its own host.
  • A new docs page covers custom subagent definitions via `--agents` or Markdown files in `.agents/agents/` and `~/.config/muse/agents/`. Up to eight agents run at once, or 64 at max or ultra effort.
  • `muse mcp list`, `get`, `add`, `add-json` and `remove` manage MCP servers from the command line.
  • The TypeScript and Python SDKs gain `session.run` and many session helpers, and `muse acp` is on by default for editors such as Zed (experimental).
  • Smaller changes include an 'Always allow outside the sandbox in this workspace' choice, a `prompt.surfaces` setting, image reading for Claude models and lighter session logs.

Reaching into a session that is already running is the theme of this week. You can now list live sessions, attach a second terminal, let several clients drive one session and message it from the command line. Around that core sit per-session hosts, custom subagent definitions, MCP management from the CLI and SDK additions.

This update covers Week 46, November 10-13, 2026: versions 1.4.15 to 1.4.20, six releases and 553 changelog entries. Most of the headline material landed in 1.4.15.


Attach to a running session and drive it together

Find the session first. muse sessions --json lists the sessions running on this machine. For each one it shows who opened it and whether it can be attached. Add --watch (muse sessions --watch --json) and the list keeps printing as sessions start and end, which suits a script or a dashboard.

Attach as a second driver. muse attach <session-ref> opens your terminal on a session that is already running, as a second driver on the same timeline. If the reference is unknown, ambiguous, points to a session that is not running, or to one that is not attachable, the command refuses with the reason and opens no terminal. You get an explanation instead of a half-working window.

Co-driving has rules. Several clients connected to the same session host can drive one session together. Each session/resume joins as a co-driver, where it used to be refused with sessionInUse. The rules for what happens when two people type at once:

  • Submissions run one at a time, in order.
  • A submit that arrives while the session is busy queues, unless it asks to steer or replace.
  • driveHolder names the earliest live driver.

(Whether the queueing feels natural with two humans at the keyboard is something to try, not something to assume.)

Message sessions from the command line. You can also send messages to running Muse sessions from the command line, including from the session itself. The commands and details are in the session messaging documentation.


Changes for everyday work

Per-session hosts. muse attach --stdio <SESSION_ID> [-- <serve flags>] connects a client’s stdin and stdout to the host that holds a session. If no host holds it, the command starts the session’s own host with the serve flags you pass. It works the same locally and over ssh. A started host does not take --trust-workspace. The command exits with code 4 when a TUI, muse exec or an older muse already holds the session.

muse serve --per-session serves each connection from a fresh host of its own. That host lists its sessions, so another client can open and steer them with muse attach --stdio <id>. Answers and notifications match plain muse serve, with two differences: the host keeps running after your input ends (so no session/closed arrives), and its diagnostics go to a log file instead of stderr. It does not take --trust-workspace either.

Custom agent definitions for subagents. A new docs page on agents covers how you control the subagents the lead session spawns. By default they run on the lead’s model. You can ask for another model in a prompt, using the exact model ID, which must appear in your /models list. Or you can define named agents:

  • Pass a JSON object with --agents on every start, resume or muse exec run. The flag may appear only once per command.
  • Save Markdown files in .agents/agents/ (project, loaded only after you trust the workspace, so you can commit them and share them with the team) or in ~/.config/muse/agents/ (user).

Each definition needs a description and a prompt. It can also set model, effort, tools and disallowedTools. The description is capped at 4,096 bytes. Agents can narrow the lead’s tools but never expand them, and they stay inside the same permission boundary. When definitions collide, managed ones take precedence over --agents, project, user, plugin and built-in definitions, in that order.

By default up to eight agents run at once, counting the lead, or 64 when the lead runs at max or ultra effort. agents.execution_capacity accepts 1 to 64.

MCP servers from the command line. muse mcp list and muse mcp get show configured servers with their source, transport and sign-in status. muse mcp add and muse mcp add-json save servers to user settings or the project file. muse mcp remove deletes them from either place. The wider context is in the extending documentation.


Technical notes

SDKs. In both the TypeScript and Python SDKs, session.run runs a whole turn in one call. It returns the final answer text, the turn’s items and its token usage, and it stops the turn on an abort signal or task cancellation. The SDKs can also list a session’s tasks, skills and hooks, pause and resume workflows, request a recap, submit feedback, open a side chat and search stored sessions without raw protocol calls. In TypeScript, MuseClient.spawn and spawnMspConnection accept a spawnFn option. That lets you run the handshake and sessions against an in-memory fake host instead of a real muse process, which helps in tests.

Editors. muse acp is on by default, so editors that support the Agent Client Protocol, such as Zed, can run Muse as their agent. The surface is experimental and may change in a later release.

Proxies and discovery. MCP servers and hooks now receive your proxy settings (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY). Session discovery lists up to 128 local and Claude sessions, up from 64.

Approvals and scheduling. The approval prompt for running a command outside the sandbox now offers ‘Always allow outside the sandbox in this workspace’. Later runs of that command there skip the prompt. Older Muse versions can’t resume a session that showed this choice, so mixed-version setups deserve a thought. The agent also leaves a notice when it creates a goal or a cron job for you, and /cron lists and removes your scheduled jobs.

Prompt and models. The new prompt.surfaces setting turns developer-prompt blocks off by id. You can set it in global or project settings, or per session. The five protected blocks stay on. Claude models can now read images: attached images, images a tool reads and images in a resumed session reach the model instead of failing the turn. When the agent reads an image file, it also sees the pixel width and height, plus the original size if the image was scaled down.

Terminal UI. Resuming a long session no longer scrolls the whole history through the terminal. It shows the newest part that fits the scrollback, with a note that earlier conversation is not shown. The UI follows your terminal’s light/dark switch while a session runs, in terminals that report it (Ghostty, kitty, Contour), unless you fix a theme in /theme. If you type into a prompt recalled with Up, your unsent message is no longer discarded. The recalled prompt shows · edited, and Down or Esc brings your message back.

Disk space. The goal reminder and verify reminder no longer save a separate log file for each check, so sessions take less disk space. Set child_session_log to retained under the plugin’s settings to keep those logs.


What to take away

If you work mostly in the terminal:

  • Run muse sessions --json while a session is going, then muse attach <session-ref> from a second terminal and see how the shared timeline behaves.
  • Try the Up-recall edit flow: type into a recalled prompt, then use Down or Esc to get your own message back.
  • If you want a fixed look, set it in /theme, since the UI now follows your terminal’s light/dark switch.

If you run parallel sessions:

  • Test co-driving with two clients on one host and watch how a busy submit queues.
  • Write one subagent definition in .agents/agents/ with a narrowed tool list, and check agents.execution_capacity against what you actually need.
  • If you relied on the per-check goal and verify logs, set child_session_log to retained.
  • For remote work, try muse serve --per-session with muse attach --stdio <id>, and remember the exit code 4 when something else already holds the session.

If you administer integrations and company deployments:

  • Use muse mcp list and muse mcp get to audit source, transport and sign-in status, and muse mcp add, add-json and remove to script changes.
  • Check that your proxy variables reach MCP servers and hooks as intended.
  • Decide whether ‘Always allow outside the sandbox in this workspace’ fits your policy, and whether prompt.surfaces needs a project-level default.
  • Note that sessions showing the new approval choice can’t be resumed by older Muse versions.
  • Treat muse acp as experimental before standardizing editors on it.

Sources: the Muse Code changelog, versions 1.4.15 to 1.4.20 (November 10-13, 2026), and the Muse Code documentation pages on session messaging, agents and extending. muse acp is experimental, so its availability and behavior may change in a later release.

Patrick Zandl trains teams in Claude Code and agentic software development in Prague and writes about what actually works in real-world AI-assisted projects. Follow on LinkedIn

Read next

Get the next one by email

Every Tuesday: what changed in Claude Code, Codex and other coding agents, plus new articles. No spam.