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

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).

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.

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).

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.

Close a pane, terminating its shell.

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

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.

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.

Focus a pane (and its tab/window).

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

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).

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

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 (tabId, tabTitle, tabColor, tabStatus: working iff any pane in the tab is busy, else idle), and the resource URI for streaming each pane's output.

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.

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.

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.

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.

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.

Move a LIVE pane to another tab, in the same window or another one, without restarting it: the pty, session, paneId, label, subtitle, meta and inbox are untouched; only its tab changes. Give exactly one target: tabId (an existing tab, as list_panes reports it), newTab ({title?, color?}: a new background tab), or project (a remembered project id, name or absolute path: that project's tab in the window, reused if present, else created with the project's name and colour). windowId picks the window for newTab/project (default: the pane's own). Returns the target tabId. A tab emptied by the move closes; the window's only pane cannot move (409). Needs a hyperpanes app with the movePane command.

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.

Open a new pane. With no tabId/projectTab/windowId it opens beside the caller, in the calling pane's own tab (HYPERPANES_PANE_ID); outside hyperpanes, or with only windowId, it opens in that window's active tab (default: 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.

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 one existing tab (returns the new pane ids): tabId if given, else the calling pane's own tab when no windowId is given either, else the window's ACTIVE tab. With no windowId, new tabs open in the calling pane's window. Each group is one tab: { title?, color?, layout?, panes:[{ command?, args?, label?, cwd?, shell?, color?, meta? }] }. A group color ("#rrggbb"/"#rgb") is the new tab's manual colour, the same one recolor_tab sets (it overrides a pane-group colour); a pane color is that pane's frame colour.

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.

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

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.

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. The inbox is in-memory and starts over (seq back at 1) when the app restarts: epoch names the current inbox, and reset:true means your after cursor predates it, so messages is the whole backlog — re-base your cursor on latestSeq. For live delivery, subscribe to the pane's messages resource instead of polling.

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. A screen read also returns inputLine {text, kind: empty|typed|suggestion} for a Claude-style prompt box (null if none): suggestion is the agent's own faint ghost text that nobody typed — never relay or submit it as someone's input. For continuous streaming, subscribe to the pane's output resource instead.

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

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.

Set a tab's colour (a stripe and tint on its tab chip), applied live and saved with the session. color is "#rrggbb" or "#rgb"; null clears it back to the default (or, on a pane-group tab, back to the group's project colour, which a manual colour overrides). Address the tab by the tabId list_panes reports.

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

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.

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

Change a tab's title, applied live to the tab strip. Address the tab by the tabId list_panes reports. The app trims the title and rejects an empty one.

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).

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.

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.

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). An org pane (role goals-orch/spec, or hp.nudge=on) also gets a one-line inbox nudge typed in when idle; pass nudge:false only when you wake the target yourself some other way, so one message does not cost it two turns.

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.

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

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 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.

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).

Spawn a pool of queue workers in one call (#6). Worker panes open beside the caller (in the calling pane's tab) unless tabId, projectTab or windowId says otherwise. 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.

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

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

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.

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, plus app (the running hyperpanes version, and build when reported). 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.