Get Onda app info: version, process ID.

Get the Onda context for the terminal where this AI agent is running. Returns paneId, tabId, workspaceId. Use this FIRST to know which pane/tab you are in before splitting or sending commands.

High-level macro: ensure workspace exists → mount it in target window → add a terminal pane → spawn bin with args (or prompt as single argv). Atomic from the agent's point of view. Supports placement modes: "auto" (default), "current-window", "window:", "new-window", "ask-user" (interactive — see below).

Placement "ask-user": the tool does NOT proceed. Instead returns { needsDecision: true, options: [{placement, label}], workspace }. The host agent must surface the choice to the human user and re-invoke this tool with placement set to a concrete value (e.g. "window:w-abc").

On success returns { windowId, workspaceId, terminalId, paneId, pid }.

Close a specific pane by ID. If no ID given, closes the active pane.

Focus (activate) a specific pane by its ID.

List all panes in the active tab. Returns pane IDs, terminal IDs, and content types. Use this to discover available terminals before sending commands.

Split the active pane in Onda terminal. Creates a new terminal beside or below the current one. Use this to set up parallel workspaces for multi-agent workflows.

Health check - verify Onda is running and responsive.

Get current Onda session state: active workspace, active tab, active pane, and their details. Use this to understand the current context before taking actions.

Close a tab by ID. If no ID given, closes the active tab.

Open a new tab and spawn a process directly with exact argv (bypasses shell parsing). Use this when you need to pass multi-line strings or special characters as a single argument — e.g. launching claude with a structured preamble. The process replaces the shell in the tab's PTY: argv is passed to execve() as-is, so embedded newlines, quotes, and dollar signs are preserved verbatim.

Switch to (focus) a specific tab by ID.

List all tabs with their IDs, titles, active state, and workspace.

Create a new tab in Onda. Each tab has its own layout of panes. Use this to isolate different workstreams.

Kill a terminal process by ID.

List active terminals. Each entry: { id, pid, cwd, alive, workspaceId, paneId, tabId, windowId }. Use the optional filters to scope the list. Essential to disambiguate which terminal belongs to which workspace/window when many are alive — no more cwd reverse-lookup.

List currently attached listeners for a terminal. Returns name + sessionId + timestamps. Used to inspect who is observing a terminal (introspection / debugging).

Long-poll a subscribed terminal session for new output. Blocks up to timeoutMs (default 15000) waiting for new chunks. Returns immediately if data is already pending. Each call advances the cursor; only data emitted after the last poll is returned. Use in a loop: subscribe -> poll -> poll -> ... -> unsubscribe.

Read recent output of a terminal (ring buffer ~200 KB / ~1 MB if a listener is attached). Returns the current buffer content plus byte total and timestamps. Use to see what a terminal has printed without subscribing to a live stream. Lazily attaches a passive tap on first call — no impact on the terminal itself.

Run a command in a specific terminal (sends command + newline). Use this to execute shell commands, launch processes, or start other AI agents in separate terminals.

Send raw text to a terminal without appending a newline. Use for interactive input, partial commands, or key sequences.

Send semantic key sequences to a terminal (Ctrl+C, Up, Enter, Esc, F5, Tab, ...). Each entry in keys is mapped to the appropriate stdin bytes. Supports Ctrl+, Arrow keys, Function keys F1-F12, Enter/Tab/Esc/Backspace/Delete/Home/End/PageUp/PageDown/Insert/Space, and raw literal text as fallback. Use this for tmux-like control instead of onda_terminal_send when you need to type special keys.

Spawn a binary inside an EXISTING pane by writing exec bin args... into its PTY. Preserves multi-line/quoted argv elements verbatim (each one becomes a single execve argv entry after shell quoting). Use this to launch claude (or any agent) with a structured prompt inside a workspace pane created via onda_workspace_add_terminal. Either paneId or workspaceId is required; if workspaceId, the first terminal pane in that workspace is used.

Attach a long-lived listener to a terminal's output stream. Returns a sessionId for use with onda_terminal_poll. Also returns the current buffer snapshot so the listener has full context. Cap of 4 concurrent listeners per terminal. The listener's name is shown in the Onda UI as a presence indicator.

Detach a listener session. Idempotent. Always call this when done to free the ring buffer (drops back to idle size after the last subscriber leaves).

Block until a regex pattern matches new terminal output, or timeout. Useful to synchronize scripted command sequences: run command -> wait for prompt -> run next command. Pattern is a JavaScript regex string; flags default to "m" (multiline). Returns { matched: bool, match?: string }.

Bring a specific main window to the foreground (restore if minimized, raise, focus). When windowId is omitted, focuses the primary window. Returns { success, windowId }. Use after mounting a workspace remotely, or to wake Onda from a background CLI subagent.

List all Onda main windows. Returns { windows: [{ windowId, isFocused, title, workspaceIds[], activeWorkspaceId, uiMode }] }. Use this before placing a new workspace/terminal to know what windows exist and which workspace lives in which window.

Mount a workspace in a specific window. Idempotent when the workspace is already there. If the workspace is currently mounted in another window, orchestrates an atomic transfer via the unmount-request flow (same path the in-app "Move workspace here?" dialog uses). Returns { success, workspaceId, windowId, transferred }. Pass direction to control how the new tile is spliced into the mosaic (mirrors the Cmd+P picker: Enter = down, Cmd+Enter = right).

Open a fresh empty main window (analogue of File > New Window). Returns { windowId }. Useful when an agent needs to host a workspace in a brand new window without contaminating existing ones.

Capture a PNG/JPEG snapshot of an Onda main window for visual debugging. Returns either a base64 dataUrl or a tempfile path. Use this when you (the agent) need to SEE what the user sees — verifying a layout change, confirming a feature renders correctly, or investigating UI glitches. Returns { dataUrl | path, width, height, windowId, capturedAt }. Defaults: focused window, PNG format, dataUrl=true.

Add a new terminal pane to a workspace and wait for its PTY to be ready. Returns { success, terminalId, paneId, workspaceId, windowId, ready }.

Placement: by default the new pane is appended via react-mosaic's built-in logic (typically "split right"). For deterministic placement, pass direction and (optionally) relativeToPaneId — this routes through splitPane and gives you explicit control.

CALL onda_workspace_layout FIRST when you care about placement: it returns the current mosaic tree + active pane + viewport, so you can decide whether to stack "down" (output-heavy panes) or split "right" (parallel-watch panes).

Create a new workspace. Workspaces group tabs by project.

Switch to a workspace by ID.

Read the current layout of a workspace: mosaic tree, list of pane IDs, active pane, viewport dimensions, and per-pane cwd. Use this BEFORE spawning a new terminal to decide where to place it (right/down/replace) and whether the viewport has room. Returns null for workspace if the id is unknown. Omit workspaceId to use the active workspace.

List all workspaces. Each entry: { id, name, rootPath, mountedIn }. mountedIn is the windowId hosting that workspace, or null if not currently mounted. Use this with onda_window_list to map workspaces ↔ windows.

Find a workspace by name, id, or rootPath without listing them all. Returns { workspace: { id, name, rootPath, mountedIn } } or { workspace: null }. mountedIn is the windowId currently hosting the workspace, or null if not mounted.

Set the workspace-level tiling layout. Controls how workspaces are arranged in the main window.

Remove a workspace from whichever window currently hosts it (drops it from that window's tiled mosaic and releases the mount registry slot). The workspace continues to exist in the global list — only its on-screen mounting is dropped. Returns { success, workspaceId, windowId, alreadyUnmounted }.