List the tab layouts hyperpanes supports (auto, single, columns, rows, grid, main-stack) with descriptions. Use these ids for a group/tab layout.

Validate a workspace spec against the hyperpanes schema without launching anything. Returns { valid, errors?, summary } where summary counts windows/tabs/panes. Accepts the nested windows[]->groups[]->panes[] shape or the legacy single-window panes[]/groups[] shape.

Validate a workspace spec and return canonical workspace JSON. Optionally write it to path (a .json file). Also returns the equivalent hyperpanes CLI command when the spec is losslessly expressible as flags (otherwise notes which fields are JSON-only).

Launch hyperpanes with a workspace. Provide either path (an existing .json) or spec (a workspace object). Requires a launcher: pass launcher or set the HYPERPANES_BIN env var (hyperpanes has no PATH binary). mode defaults to "file" (writes a temp .json — lossless); "cli" compiles to flags (drops JSON-only fields like bounds/active/subtitle).

Check whether the hyperpanes control API is reachable and whether input is allowed. Reports the app pid/version, the bridge-side send_input gate, and the control.json path. Call this first if other control tools fail.

List all panes across all windows/tabs of the running hyperpanes instance, with status, activity (busy/idle/exited liveness heuristic), any org metadata (role/parent/agentType/task), tab/window context, and the resource URI for streaming each pane's output.

Read a pane's terminal output. mode:"transcript" (Claude panes only) returns the pane's actual CONVERSATION — the last messages user/assistant turns from the session transcript on disk, joined via the pane's session marker — the reliable way to read a claude pane (TUI screen scrapes are lossy). mode:"screen" returns the RENDERED cell grid (what's actually on screen — no overdraw, spinner spam, or mangled spacing) instead of the raw pty stream. Default "raw". tail limits to the last N lines; strip removes ANSI escape codes from a raw read. waitForIdle BLOCKS until the pane has been output-quiet for settleMs (default 600ms) or timeoutMs (default 30000ms) elapses — the way to read a reply without polling/sleeping. since is a byte cursor (use the cursor from a prior read) that returns only NEW output (raw mode), so you don't re-scrape the whole scrollback each turn. Every read returns the current cursor. For continuous streaming, subscribe to the pane's output resource instead.

Open a new pane in the active tab of a window (defaults to the first window). Returns the new paneId. command alone runs through the shell. Pass args (a string array) to run command DIRECTLY as the executable with that exact argv — no shell, no re-parse — which is the reliable way to pass arguments containing spaces or quotes (e.g. command:"claude", args:["--append-system-prompt","…long persona…"]); a single command string with such args gets mangled by the shell. meta attaches free-form org metadata (reserved keys: role/parent/agentType/task) so the new worker is self-describing. project opens the pane in a remembered project (see list_projects/add_project): it defaults the pane's cwd + frame color from that project and bumps its recency in the sidebar rail.

Spawn a pool of queue workers in one call (#6). Opens pane(s) running the native hyperpanes worker runner bound to queue: it claims tasks and runs command (via sh -c, so $HP_TASK_PAYLOAD / $HP_TASK_ID / $HP_FENCING_TOKEN / $HP_QUEUE are in the environment) for each, acking on exit 0 and nacking on non-zero, until the queue drains — then the pane exits. count = how many competing workers; by default each gets ITS OWN pane (layout:"pane-per-worker") so you can watch one agent per pane — pass layout:"single-pane" for the legacy one-pane-runs-N behaviour. isolation:"worktree" runs each task in a throwaway git worktree that auto-removes (needs cwd to be a git repo) and REQUIRES base — the explicit committish each task worktree forks from, passed to the runner as --base (the call fails without it). stream:true renders a Claude child's --output-format stream-json events as readable progress instead of the silence a bare claude -p gives you; logDir tees each task's raw output to a file that outlives the pane; lingerSecs keeps the pane open after the queue drains. The runner binary defaults to hyperpanes on PATH (override with HYPERPANES_WORKER_BIN on the bridge). env/accounts/meta/project/subtitle pass through to each worker pane spec — merge order: env is the shared base, accounts[i % len] sets each pane's CLAUDE_CONFIG_DIR and wins over env (rotation requires layout:"pane-per-worker" when count > 1; single-pane shares one process env, so the call fails loudly). Every worker pane is stamped with default org meta role="worker", task="queue:", parent=<this bridge's pane> (so worker send_to_parent works out of the box); caller meta wins over those defaults. Returns the spawned pane ids.

Attach one or more new tabs to an existing window (defaults to the first window), each with fresh shells — the programmatic equivalent of hyperpanes --attach. Returns the new tab ids. Use this (not open_pane) to add a whole tab, or several tabs, in one call. Pass as:"panes" to instead merge ALL the given panes into the window's ACTIVE tab (returns the new pane ids). Each group is one tab: { title?, layout?, panes:[{ command?, args?, label?, cwd?, shell?, color?, meta? }] }.

List the projects (remembered directories) the running hyperpanes instance tracks — its sidebar rail — newest-opened first. Each has an id, absolute path, name, frame color, and lastOpenedAt. Use an id (or name) with rename_project/recolor_project/remove_project, or as open_pane's project option to open a pane in it.

Remember a directory as a project (the programmatic equivalent of the sidebar PROJECTS ＋ button). The path must exist and be a directory; a git repo is NOT required. Adding an already-known directory is a no-op — returns added:false with the existing entry. Returns the project (id/path/name/color).

Rename a remembered project by id (find ids with list_projects). The new name shows in the sidebar rail.

Set a remembered project's frame/dot color by id (find ids with list_projects). Pass a hex color like "#a855f7"; the app retints open panes inside that project too.

Forget a remembered project by id (find ids with list_projects). Removes it from the sidebar rail; does NOT delete the directory on disk.

Attach or update free-form metadata on a pane (merged: a string value sets/overwrites a key, an explicit null DELETES that key, untouched keys are kept). Reserved keys role/parent/agentType/task describe an agent org; the rest is open. Returns the TRUE merged metadata read back from the app (not your raw input). This is how an orchestrator records the org chart as data.

Set the tiling layout of a tab. tabId defaults to the active tab of the first window. Use list_layouts for valid ids.

Focus a pane (and its tab/window).

Close a pane, terminating its shell.

Kill and respawn a pane's shell. With resume:true, the pane's live Claude conversation (per its session marker) is resumed in its own cwd after the respawn — an agent may target its OWN pane to restart itself. prompt queues a message typed into the resumed claude the moment it is ready (speak-first); requires resume:true.

Durably queue a message for a Claude conversation (by session id). It is typed into the owning pane the next time that session is ready — including after a pane restart, an app relaunch, or a reboot. Deliver-once; survives every process involved.

Restart the hyperpanes app itself (root token only). scope:"gui" relaunches the GUI — panes and their processes survive via the session daemon and re-attach. scope:"full" is the phoenix: a final workspace snapshot is flushed, GUI AND daemon exit (every pane dies), and the relaunched app restores the workspace, auto-resuming every pane's Claude conversation in its own cwd. Optional sessionId+prompt pre-queues a speak-first message for one resurrected conversation (e.g. the caller's own — self-restart across the apocalypse).

Change a pane's label (title) and, optionally, its subtitle — applied live to the pane header. Pass subtitle:"" to clear it; omit subtitle to leave it unchanged.

Change a pane's frame color, applied live. Accepts any CSS color string (e.g. "#e5484d").

Type text into a live shell. With submit:true the app writes your text, then a SEPARATE bare Enter a beat later — the reliable way to submit a line to a TUI agent (a trailing "\n" in one write is read as a bracketed paste, not Enter). Without submit, include a trailing newline yourself to run a shell command. DANGEROUS: this executes whatever you send in a real terminal. Triple-gated and never on by default — requires (1) the app's "Allow agent control → input" toggle, (2) HYPERPANES_ALLOW_INPUT=1 on this bridge, and (3) confirm=true on every call. See README "send_input safety model".

Send a sequence of named keys to a live pane as the right terminal bytes: enter, escape, tab, shift+tab, up/down/left/right, home/end, pageup/pagedown, backspace, delete, space, and ctrl+ (e.g. ctrl+c). For menus, y/n and trust prompts, and cancelling — things a text string can't express. Same triple gate as send_input (it IS input): app toggle + HYPERPANES_ALLOW_INPUT=1 + confirm=true.

Drive one full turn of a TUI agent (e.g. a live claude) in a pane with ONE call: type text, submit it cleanly (a separate Enter), wait for the pane to go output-quiet, then return the RENDERED screen transcript and whether it is now awaiting input. The wait is turn-aware — it won't return on the pre-prompt screen, only once the reply has begun and settled. Composes send_input(submit) + read_pane(waitForIdle, mode:"screen"). Same triple gate as send_input (it IS input): app toggle + HYPERPANES_ALLOW_INPUT=1 + confirm=true.

Turn per-pane talk on/off: while enabled, the pane speaks NEW Claude assistant replies aloud via local TTS. Off by default. Returns the resolved talk state and TTS backend (plus a warning if the backend has a problem, e.g. missing binary).

Set global speech (TTS) settings: muted mutes/unmutes all speech output; focusedOnly restricts speaking to the currently focused pane. Provide at least one of the two.

Immediately kill any in-flight speech utterance and clear the speech backlog (global one-shot).

Identify the pane this MCP bridge is running inside (from HYPERPANES_PANE_ID) and report its org metadata (role/parent/agentType/task) + window/tab context. The recursion enabler: a manager-agent-in-a-pane calls this to learn who it is before driving its sub-workers. Optionally pass paneId to describe a specific pane instead.

Read a pane's durable message inbox (agent-orchestration E). after is a cursor — pass the highest seq you have seen to get only newer messages. dropped reports how many were evicted by the per-pane cap. For live delivery, subscribe to the pane's messages resource instead of polling.

Enqueue a structured message to a pane's durable inbox (agent-orchestration E). Delivered at-least-once; the target reads it via read_messages or its messages resource. from should identify the sender (your paneId, or an orchestrator label).

Message this pane's org parent — resolved from its meta.parent (agent-orchestration E). Requires HYPERPANES_PANE_ID (this bridge runs inside a pane), or pass from explicitly. Errors if the pane has no parent set.

Send a message to every pane in an org subtree — all panes whose meta.parent chain leads back to root (agent-orchestration E). root defaults to HYPERPANES_PANE_ID. Returns the list of recipients.

Mint a subtree-scoped control token (agent-orchestration F). The new token can only reach the named windows/tabs/panes, and only within the minting token's own authority (no escalation). Hand it to a child via open_pane env: { HYPERPANES_CONTROL_TOKEN: token, HYPERPANES_CONTROL_PORT: port } — the child then controls only its subtree and never sees the master token. Optional ttlMs expires it.

Take an advisory write lock on a pane (agent-orchestration H) so only this owner can send_input until it expires or is released. Advisory: an unlocked pane is writable by anyone. Renew by acquiring again as the same owner. Pass the same owner to send_input while holding it.

Release an advisory write lock you hold on a pane (agent-orchestration H).

List every work queue and its depth (pending/claimed/etc. counts). Scope-filtered to the token. The work queue is the durable job queue behind the control server; use it to fan work out to competing workers.

Append a task to a work queue (created on first use). payload is the opaque task body (often JSON) a worker reads after claiming. Optional: kind/title for triage, priority (higher runs sooner), maxAttempts (auto re-queue up to N on nack/lease-expiry), visibilityTimeoutMs (default lease), delayMs (schedule into the future), dedupeKey (collapse duplicate enqueues), and — for the goals system — goalId (tag the task to a goal) and dependsOn (task ids that must all reach done before this task becomes claimable; a DAG gate). Returns the new task id + seq.

Claim the next task(s) off a queue for worker (competing consumers — each task goes to exactly one claimer). An empty queue returns {tasks:[]} (not an error). Each returned task carries a fencingToken and visibilityDeadline — keep them: ack/nack/extend need the token, and the task returns to the queue if you do not ack/extend before the deadline. count prefetches several; leaseMs overrides the task default lease.

Mark a claimed task done. Must carry the fencingToken from the claim (lease fencing). result is an optional stored outcome string.

Report a claimed task as failed. By default it is re-queued until maxAttempts is exhausted (then it lands in dead). Must carry the claim fencingToken. delayMs backs off the retry; requeue:false fails it immediately without retrying.

Heartbeat a long-running task: extend its lease by extraMs so it is not reaped and handed to another worker. Must carry the claim fencingToken.

Fetch one task by id (state, payload, attempts, lease, timestamps). Returns task:null if it does not exist.

List/inspect tasks in a queue. Optional state filter (queued/claimed/done/failed/dead), after (seq cursor — pass a prior result's latest seq to page) and limit (default 100, max 1000). Returns the tasks plus per-state counts.

Drop TERMINAL tasks (done/failed/dead) from a queue for retention/cleanup. In-flight (queued/claimed) tasks are kept. Returns how many were removed.