Level

Needs a running app?

What it does

Compose & launch

No

Generate/validate a workspace config and shell out to hyperpanes to open it.

Live control

Yes

Talk to the app's loopback control API to inspect/drive panes and stream output.

Tool

Description

list_layouts

List the tab layouts (auto, single, columns, rows, grid, main-stack) with descriptions.

validate_workspace

Validate a workspace spec against the schema. Returns { valid, errors?, summary } (window/tab/pane counts).

build_workspace

Validate + return canonical workspace JSON; optionally write it to a .json file; include the equivalent hyperpanes CLI command when losslessly expressible.

launch_workspace

Launch hyperpanes with a workspace, from a .json path or an inline spec. Defaults to a lossless temp-file launch; mode:"cli" compiles to flags. Needs HYPERPANES_BIN.

Tool

Description

control_status

Is the control API reachable? Reports app pid/version, whether the app allows input, the bridge-side send_input gate, and the control.json path. Call this first.

list_panes

All panes across windows/tabs, with status, activity (busy/idle/exited), org metadata, tab/window context, and each pane's output-resource URI.

read_pane

A pane's terminal output. mode:"screen" = the rendered cell grid (clean TUI transcript, no overdraw/spinner spam); tail = last N lines; strip = ANSI-stripped raw text; waitForIdle = block until the pane goes output-quiet (settleMs/timeoutMs) so you read a reply without polling; since = a byte cursor for delta reads (only new output). Every read returns the current cursor.

read_messages

Drain a pane's durable message inbox past a cursor (after = highest seq seen).

whoami

Identify the pane this bridge is running inside (HYPERPANES_PANE_ID) and its org metadata — so a manager-agent-in-a-pane can learn who it is before driving sub-workers.

Tool

Description

open_pane

Open a new pane in a window's active tab (defaults to the first window). Returns the new paneId; accepts meta (org metadata) and env (e.g. a scoped token) at spawn. Pass args (a string array) to run command directly with that verbatim argv — no shell, no re-parse — the reliable way to pass arguments containing spaces/quotes (e.g. command:"claude", args:["--append-system-prompt","…persona…"]).

set_layout

Set a tab's tiling layout (defaults to the first window's active tab).

focus_pane

Focus a pane (and its tab/window).

close_pane

Close a pane, terminating its shell.

restart_pane

Kill and respawn a pane's shell.

rename_pane

Change a pane's label and (optionally) subtitle, live.

recolor_pane

Change a pane's frame color, live (any CSS color).

set_meta

Attach/update a pane's free-form metadata (merge; null deletes a key). How an orchestrator records the org chart as data.

Tool

Description

send_input ⚠️

Type text. submit:true writes your text, then a separate Enter a beat later — the reliable way to submit a TUI line (a trailing \n in one write is read as a bracketed paste, not Enter).

send_keys ⚠️

Send named keys as the right terminal bytes: enter, escape, tab, shift+tab, arrows, home/end, pageup/pagedown, backspace, delete, space, ctrl+<letter>. For menus, y/n & trust prompts, and cancelling.

prompt_pane ⚠️

One full turn in one call: type → submit → wait for the pane to settle → return the rendered transcript + whether it's now awaitingInput. The way to converse with a TUI agent in a pane.

Tool

Description

send_message

Enqueue a structured message to a pane's durable inbox (at-least-once delivery).

send_to_parent

Message this pane's org parent (resolved from meta.parent).

broadcast_subtree

Message every pane in an org subtree (all panes whose meta.parent chain leads back to a root).

mint_token

Mint a subtree-scoped control token (no escalation) to hand a child via open_pane env — the child controls only its subtree and never sees the master token.

lock_pane

Take an advisory write lock so only the holder can send_input until it expires.

unlock_pane

Release an advisory write lock you hold.

Tool

Description

list_queues

Every queue and its per-state depth.

enqueue_task

Append a task (payload + optional kind/title/priority/maxAttempts/visibilityTimeoutMs/delayMs/dedupeKey). Returns the task id + seq.

claim_task

Claim the next task(s) for a worker (competing consumers; empty → {tasks:[]}). Each task carries a fencingToken + visibilityDeadline.

ack_task

Complete a claimed task (carry the fencingToken).

nack_task

Fail a task — re-queued until maxAttempts, or requeue:false to fail now; delayMs backs off.

extend_task

Heartbeat a long task: extend its lease so it isn't reaped.

get_task

Fetch one task (state, payload, attempts, lease, timestamps).

list_tasks

List/inspect a queue's tasks with a state filter + after/limit paging.

purge_queue

Drop terminal tasks (done/failed/dead) for cleanup.

Resource URI

Content

hyperpanes://pane/{paneId}/output

Terminal output — scrollback on read, deltas on subscribe (text/plain).

hyperpanes://pane/{paneId}/messages

The pane's durable message inbox — JSON on read, live deliveries on subscribe.

Env var

Purpose

HYPERPANES_BIN

Path to the hyperpanes executable (for launch_workspace). No PATH fallback — it fails loudly rather than spawn the wrong process.

HYPERPANES_LAUNCH_ARGS

Whitespace-separated leading args for the launcher (e.g. a dev runner).

HYPERPANES_CONTROL_FILE

Override the path to the app's control.json (use if the app runs under a non-default data dir).

HYPERPANES_USER_DATA

Override just the userData dir; <dir>/control.json is used.

HYPERPANES_CONTROL_TOKEN / HYPERPANES_CONTROL_PORT

A scoped control token + port for a child pane (set automatically by mint_token / open_pane env). Used instead of reading control.json.

HYPERPANES_PANE_ID

The pane this bridge runs inside — enables whoami and the hierarchy helpers.

HYPERPANES_ALLOW_INPUT

1/true to permit send_input on this bridge (off by default).

HYPERPANES_INPUT_ALLOWLIST

Comma-separated pane ids or labels allowed to receive input.