Primary agent orchestration tool: recover a v2.1 agent response. Use pmux_capture_pane only as a low-level fallback. If requestId is supplied, first read the report file at workspaceDir/.pmux-agents//turn-.md and require matching status line plus EOF marker. Without requestId, file recovery is skipped and pane BEGIN/END fallback is used. Returns structured complete/blocked/working/inconsistent/partial/missing results; partial/working means do not send the next turn yet.

Primary agent orchestration tool: validate provider-specific readiness/busy/error state, optionally verify a previous DONE signal or END marker, append the v2.1 PMUX footer, and send the prompt. Use pmux_send_input/pmux_capture_pane only as low-level fallbacks. For fileOutput=true previous turns, pass expectPrevTurnEnd together with expectPrevRequestId so shortened req-keyed markers can be matched. On turn <= 1 only, pane fallback input_queued is treated as a composer placeholder and sent with validation.warning; later turns remain strict. fileOutput defaults true: requestId is generated when omitted, workspaceDir is resolved from workspaces[].directories[0], and expectedReportFile is returned. Use fileOutput:false when pmux_agent_start returned recommendedFileOutput:false; read-only/plan agents cannot write report files. fileOutput=false uses the pane BEGIN/END fallback. agent_busy returns {sent:false, reason:"busy"}. Caller contract: if pmux_agent_capture returns partial/working, do not call pmux_agent_send again until the current turn completes or is explicitly abandoned.

Primary agent orchestration tool: create a terminal tab, poll briefly for shell readiness, then send an interactive agent CLI command. ORCHESTRATOR CONTRACT: before launching, ask the user which model/effort (and codex sandbox / claude permissionMode) each subagent should use, unless the user already specified them. Use pmux_send_input/pmux_capture_pane only as low-level fallbacks. Returns recommendedFileOutput: false for read-only/plan agents that should be sent fileOutput:false. Boot verification: returns bootId — by default (bootstrapEcho:true) the CLI is launched with a fixed initial prompt that makes the model print a DONE marker (req=bootId), and a SessionStart hook writes a boot-signal file; verify with pmux_agent_wait_ready {bootId, expectEcho:true}, then send user work from turn=1 (bootstrap consumed turn 0; do not pass expectPrevTurnEnd on turn 1). bootstrapEcho costs one tiny model turn — pass false to skip. codex hook trust (실측 2026-07-08): the FIRST launch that wires the boot hook requires a one-time interactive trust approval in the codex TUI — until approved, boot.fileSeen stays false while the echo still works; treat fileSeen:false + echoSeen:true on codex as this case, not a failure. This is non-blocking: after a successful start return, use pmux_agent_wait_ready before sending work. wait_ready launch_failed is meaningful only after start has successfully sent the command; an idle shell before command send is indistinguishable to the stateless wait tool. Session lifetime contract: keep the tab open until the task is finished, then close it with pmux_close_tab. Codex command: codex --no-alt-screen -s ; Claude permissionMode choices are based on claude 2.1.201 and intentionally exclude bypassPermissions; claude effort maps to the --effort flag (claude >=2.1.202).

Primary agent orchestration tool: return a no-wait v2.1 status snapshot. Use pmux_tab_status/pmux_capture_pane only as low-level fallbacks. Includes tab alive, provider-specific readiness, optional DONE signal for agentId/turn/requestId, optional report-file check, runtimeError when detected, and pane tail. No server-side state is kept.

Primary agent orchestration tool for one full turn: send a prompt, poll for completion evidence, then return the recovered response. Safe to call immediately after a previous turn; transient pre-send busy/starting states are retried within the same pollTimeoutMs budget. Use pmux_agent_capture with the returned marker to resume after timeout; use pmux_send_input/pmux_capture_pane only as low-level fallbacks. Completion evidence from a valid report file or pane markers wins over readiness/runtime-error signals. Without completion evidence, ready plus runtimeError returns status:"agent_error".

Primary agent orchestration tool: poll a tab until an agent is ready, still starting/busy, launch_failed, exited, or timeout. Use pmux_send_input/pmux_capture_pane only as low-level fallbacks. agent_busy is non-terminal and keeps polling. Boot verification (recommended after pmux_agent_start): pass {bootId, expectEcho:true} — agent_ready is then returned ONLY on the bootstrap DONE marker (completion evidence; supersedes ready heuristics, requireBusyTransition and runtimeError), and every response carries boot.fileSeen (SessionStart boot-signal file — diagnostic only; on echo timeout, fileSeen:false suggests launch/hook-trust failure while fileSeen:true suggests the model never answered). Default timeout rises to 90s under expectEcho. requireBusyTransition defaults false for boot readiness; set true when waiting after send so ready is returned only after busy was observed or an initial non-ready baseline later changes to ready. In boot mode only (and never under expectEcho), pane fallback input_queued can be treated as a composer placeholder and returned ready; send validation remains strict. Uses pane capture + tab_status only; no server-side registry is kept. Session lifetime contract: keep the tab open until the task is finished, then close it with pmux_close_tab.

Return the purplemux application's HTTP API reference as markdown (fetched from the running purplemux). This documents the underlying REST endpoints, NOT how to use this MCP server's tools — for orchestration guidance use pmux_guide.

Get browser console entries { tabId, entries[] } (ring buffer, last 500). since=ms is an incremental polling cursor; level filters by console level. Electron-only (503/409).

Evaluate a JavaScript expression in the page and return { tabId, value } (CDP Runtime.evaluate, returnByValue + awaitPromise, 10s timeout). A JS exception/timeout surfaces as 409. Electron-only: 503 = not under Electron (hard); 409 'Browser tab not attached yet' = webview not dom-ready (transient, retry shortly).

Get browser network entries { tabId, entries[] } (ring buffer, last 500). Filters: since=ms cursor, method (upper-cased server-side), url (substring), status (exact int). Electron-only (503/409). Use pmux_browser_network_body for a single response body.

Get a single network response body by requestId: { tabId, requestId, body }. Body is cached after the first call. 404 'Response body unavailable' if not cached/available. Electron-only (503/409).

Screenshot a web-browser tab. Default: returns MCP image content (PNG). With savePath: writes raw PNG bytes to that path and returns { saved, bytes }. full=true captures beyond the viewport. Electron-only (503 hard / 409 'not attached yet' transient).

Get the browser tab's { tabId, url, title }. Browser tools are Electron-only: 503 = not running under Electron (hard, don't retry); 409 'Browser tab not attached yet' = webview not dom-ready (transient, retry shortly). 400 'Tab is not a web-browser panel' on a non-browser tab.

Low-level fallback for manual pane inspection; for agent orchestration prefer pmux_agent_* tools. Capture the current pane snapshot as { content }. Not meaningful for web-browser tabs. 409 'Tab session is not running' if the session is dead.

Close a tab. Returns the real { ok:boolean } body (surfaced faithfully; the CLI would hide it). For web-browser tabs the tmux kill is skipped.

Local diagnostic: { baseUrl?, portSource, tokenSource, hasToken }. NEVER returns the token value. When port/token are missing it returns partial diagnostics (source "none", hasToken:false) rather than erroring.

Create a tab in a workspace. panelType is one of terminal | claude-code | codex-cli | agent-sessions | web-browser | diff (default terminal); invalid → 400 with validPanelTypes. WARNING: claude-code/codex-cli panelType creates a UI panel, NOT a managed agent session — the pane may be an empty shell before the UI attaches, and sending prompts into it is unreliable. To run a subagent, use pmux_agent_start instead (it launches the CLI in a terminal tab under full protocol control). Creating claude-code/codex-cli without the CLI installed → 409 with suggestedCommand. Returns the created-tab object.

Get info for a single tab by id.

Return the orchestration guide for THIS MCP server as markdown: tool layers (agent_* primary vs low-level fallbacks), the golden path for running claude/codex subagents, boot verification semantics, fileOutput routing, failure modes and recovery patterns. Call this before orchestrating subagents for the first time, or whenever an agent_* result is unclear. (For the purplemux HTTP API reference, use pmux_api_guide instead.)

List tabs, optionally filtered by workspaceId. Omit workspaceId to list across all workspaces. Unknown workspaceId returns {tabs:[]}, not an error.

List purplemux workspaces: { workspaces:[{id,name,directories}] }. Start here to get workspaceId values for the other tools.

Low-level fallback for manual tab input; for agent orchestration prefer pmux_agent_* tools. Send text to a tab. The server AUTO-SUBMITS (delivers as a bracketed paste then presses Enter) — do NOT append a newline to submit. Exactly one trailing '\n' is stripped from content; other whitespace is preserved. Returns { status:"sent" }. 409 'Tab session is not running' if the tmux session is dead.

Get tab runtime status. NOTE: for web-browser tabs alive:false is NORMAL (they are Electron webviews, not tmux) — probe health via the browser tools instead. claudeSessionId is a legacy alias of agentSessionId (same value).