Loading...
What CmuxLayer — Terminal Agent Lifecycle MCP can do
Full terminal pane control through MCP
list_surfaces, new_split, send_input, send_key, read_screen, rename_tab, set_status, set_progress, close_surface, and browser_surface. These wrap the cmux CLI socket into typed, validated tools. browser_surface alone handles 8 actions: open, navigate, snapshot, click, type, eval, wait, and url.
Spawn, monitor, and communicate with AI agents
spawn_agent launches a Claude, Codex, Cursor, Gemini, or Kiro CLI in a new pane with automatic boot detection. The agent transitions through spawning → booting → ready → working → done states. wait_for blocks until a target state is reached. send_to_agent and read_agent_output provide structured I/O with delimiter-based output extraction.
// Spawn a Claude agent
const agent = await spawn_agent({
cli: "claude",
repo: "brainlayer",
prompt: "Fix failing tests"
});
// agent.id: "agent-claude-brainlayer-x7k2"
// Wait for it to be ready
await wait_for({
agent_id: agent.id,
target_state: "ready"
});Spawn + wait lifecycle — fully typed with Zod validation
8 agent operations consolidated into 2 tools
The V2 API reduces cognitive load. interact() accepts a flat action enum (send, interrupt, model, resume, skill, usage, mcp) with optional fields per action. kill() terminates agents by single ID, array, or 'all'. If an agent isn't alive when you interact, it auto-spawns, waits for ready, then sends — zero manual lifecycle management.
// V2 interact — 7 action types
interact({ agent: "x7k2", action: "send",
message: "Run tests" })
interact({ agent: "x7k2", action: "interrupt" })
interact({ agent: "x7k2", action: "skill",
skill: "/commit" })
interact({ agent: "x7k2", action: "usage" })
// V2 kill — flexible targeting
kill({ target: "x7k2" }) // single
kill({ target: ["x7k2","m3p1"]}) // batch
kill({ target: "all" }) // everythingFlat enum actions — no discriminated unions (MCP SDK limitation)
Parent-child tracking with spawn guards
Agents can spawn child agents (K8s ownerRef pattern). parent_agent_id links child to parent. MAX_SPAWN_DEPTH=2 prevents unbounded recursion. MAX_CHILDREN_PER_AGENT=10 caps per-parent spawns. Each agent has a quality field (unknown → verified → suspect → degraded) for tracking output reliability. Sidebar sync pushes agent state to the cmux sidebar in real-time.
Command injection prevention + ID collision avoidance
Repository names are sanitized before being passed to shell commands — only alphanumeric, hyphens, underscores, and dots are allowed. Agent IDs include a random suffix to prevent collision when spawning multiple agents for the same repo. Mode enforcement: manual mode makes all mutating tools read-only.
Phase 5 orchestration platform — design converged, code next
The Phase 5 v2 design document (1676 lines, 22 converged decisions) is complete. Upcoming: events.jsonl append-only audit log for agent state transitions. BrainLayer session persistence at session end. Context degradation circuit breakers at 80% usage. Cost caps per agent. Agent trust scoring based on success history. Per-surface mode enforcement for workspace-level access control.