New Surface Type: AGENT

[Eibich]

Proposal: Introduce an "Agent" Surface Type

Summary

cmux currently offers several surface types — Terminal, Browser, Markdown, etc. I'd like to propose a new first-class surface type: Agent.

An Agent surface would wrap a TUI-based coding agent (e.g. claude / Claude Code CLI, codex CLI, and similar tools) and treat it as a distinct, identifiable entity inside cmux rather than as "just another terminal that happens to be running an agent".

Motivation

Today, when several agent CLIs run alongside regular terminals in the same workspace, all panes look essentially the same. This creates real friction:

• Hard to tell agents apart at a glance. Three Claude Code panes and a Codex pane look like four indistinguishable terminals. You have to focus each one to know which is which.
• CLI / automation control is awkward. Targeting "the agent running task X" requires bookkeeping (pane IDs, titles you set manually) that the user has to maintain.
• Notifications are coarse. A "terminal finished" or "output produced" hook can't easily distinguish "my agent is waiting for input" from "my build script printed a line".
• No structured state. The agent's lifecycle (idle / running / waiting-for-input / awaiting-permission / errored / done) is invisible to cmux, so the UI can't reflect it.

A dedicated surface type would let cmux know it's hosting an agent and treat it accordingly.

Proposal

Add agent as a surface type, parallel to terminal, browser, markdown, etc.

Each Agent surface would have the following properties:

1. Custom Name

A user-defined label (e.g. refactor-auth, migrate-db, pr-review-bot) shown in the tab bar, sidebar, and CLI listings — independent of the underlying binary.

2. Custom Icon

Choose from a small icon set (or supply a path/emoji) so multiple agents are visually distinguishable at a glance. Useful even when names are similar.

3. Status

A first-class lifecycle state surfaced in the UI:

• idle
• running
• awaiting-input (the agent is asking the user something)
• awaiting-permission (the agent is blocked on a tool/permission prompt)
• done
• error

Status could be derived via hooks the agent already emits (Claude Code, for example, has SessionStart / Stop / Notification hooks) or via pattern matching on output as a fallback.

4. Start Parameters

A structured launch config per agent surface, e.g.:

{
  "type": "agent",
  "name": "refactor-auth",
  "icon": "robot",
  "tui": true,
  "wrapper": "claude",
  "command": "claude",
  "args": ["--model", "claude-opus-4-7", "--cwd", "./packages/auth"],
  "env": { "ANTHROPIC_LOG": "info" },
  "cwd": "./packages/auth",
  "autoStart": true,
  "notifications": {
    "onAwaitingInput": "flash",
    "onDone": "system",
    "onError": "system"
  }
}

These configs would be reusable presets (similar to the existing examples library) so users can stamp out "a Claude Code agent for repo X" or "a Codex agent in review mode" with one click.

5. TUI (yes/no)

A boolean flag indicating whether the underlying agent is a full-screen TUI (uses alternate screen buffer, cursor positioning, mouse events) or a plain line-based CLI.

• tui: true — cmux preserves full TTY fidelity, forwards mouse/resize events, and avoids any output post-processing that would corrupt the rendering (Claude Code CLI, Codex CLI, etc.).
• tui: false — cmux is free to capture, parse, and annotate output more aggressively (e.g. inline status badges, clickable links, transcript scraping), since there's no full-screen UI to disturb.

This lets cmux choose the right rendering and interception strategy per agent without guessing.

6. Wrapper

The name of the agent adapter cmux should use to understand this surface — independent of the actual binary path. Examples: claude, codex, aider, cursor-agent, custom.

The wrapper determines:

• Hook/event integration — which official events cmux listens for (e.g. Claude Code's SessionStart / Stop / Notification hooks vs. Codex equivalents).
• Status detection rules — how awaiting-input / awaiting-permission / done are recognized for that specific agent.
• CLI command mapping — how cmux agent send <name> <text> is translated for the underlying tool.
• Defaults — sensible default icon, default args, default notification rules per wrapper.

A wrapper: "custom" value would let users define their own adapter (regex rules + command templates) in cmux.json for agents cmux doesn't ship built-in support for. The wrapper and command fields are intentionally decoupled so users can, for example, run a forked or aliased binary (my-claude-fork) while still using the claude adapter.

Benefits

• Visual differentiation. Custom names + icons + status badges make a wall of agents readable at a glance.
• Better CLI control. Commands like cmux agent list, cmux agent focus refactor-auth, cmux agent send refactor-auth "continue", cmux agent status become natural and unambiguous — no need to map agents to terminal pane IDs.
• Targeted notifications. Because cmux knows the surface is an agent and knows its status, notification rules can be specific: notify on awaiting-input but not on running, beep on error, surface a system notification only when an agent transitions to done. Much harder to express today.
• Correct rendering per agent. The tui flag lets cmux pick the right interception strategy without breaking full-screen UIs.
• Pluggable adapters. The wrapper field makes it trivial to add support for new agent CLIs without changing cmux's core.
• Workspace layouts. Layout presets can include agent slots ("open my standard 3-agent review workspace") instead of generic terminal slots that happen to launch agents.
• Future-proofing. Once agents are a first-class concept, additional features become natural: per-agent token/cost display, per-agent transcripts, "resume last session" semantics, cross-agent handoff, etc.

Curious what others think. Especially folks already running multiple agent CLIs side-by-side in cmux today. Does this match the pain you're hitting, and would the proposed shape solve it?