The server is its-computer, stdio transport. Every tool is a call to the running app. instanceId is a copy's id as list_instances reports it: a worktree path, or <worktree path>#run-<tag>.
Find a copy #
| Tool | Parameters | Returns |
|---|
list_instances | none | The running copies with ids and status. active: true marks the copy in focus; in_scope: true marks every copy in the chat's scope. Call this first. |
active_instance | none | The copy the user is looking at. The default target when the user says "this" or "the app". |
scope_instances | none | All copies the chat is scoped to, primary first. When two are selected for a comparison, these are the ones to act on. |
instance_ports | instanceId | The ports the copy is serving, the dev servers inside it. |
See and act #
| Tool | Parameters | Does |
|---|
screenshot | instanceId | Saves the copy's current frame to an image file and returns the path plus the frame's actual width and height. Coordinates for the tools below are in that frame, origin top-left. The frame follows the panel size, so read the returned size rather than assuming one. |
click | instanceId, x, y, button (1 left, 2 middle, 3 right; default 1) | Clicks at a pixel. |
type | instanceId, text | Types text into the focused element. |
key | instanceId, key | Presses a key or chord: Return, Tab, Escape, ctrl+a. |
scroll | instanceId, dy (default 600), dx (default 0), x, y (optional pointer position) | The same wheel scroll a person does. Positive dy scrolls down. About 300 is one notch; 600 to 900 moves a viewport. |
Do work inside #
| Tool | Parameters | Does |
|---|
sb_run | instanceId, app, args (optional) | Runs an app through sb run by typing the command into the copy's foreground terminal. GUI apps appear on screen; it does not wait or return output. |
exec | instanceId, command | Runs a shell command inside the copy under bash -lc and returns stdout, stderr and the exit code. Use this when a result is needed. |
tail_logs | instanceId, channel (optional) | The copy's log channels, the same ones the Logs tab streams: launch, npm, app, compositor, and any the workspace adds. Each channel is trimmed to its last few thousand characters. |
Lifecycle #
| Tool | Parameters | Does |
|---|
start_instance | worktreePath, netMode (private or mesh, optional), netGroup (optional) | Boots a copy from a worktree and returns its id. Add #run-<tag> to the path for a second, independent copy of the same worktree. mesh puts the copy on a shared network with other mesh copies. |
stop_instance | instanceId | Stops the copy and frees its resources. A no-op on a stopped copy. |
restart_instance | instanceId, netMode, netGroup (optional) | Stops and starts the same id. This is how a network mode is changed; a running copy cannot switch live. Returns once the restart is under way. |
Background tasks #
| Tool | Parameters | Does |
|---|
spawn_task | goal, maxIterations (1 to 200, default 30) | Starts a goal loop: a fresh agent session per iteration with the history replayed, until a reply ends with GOAL DONE:, the cap is hit, or the user pauses or cancels. Inherits the chat's worktree and profile. Refused from inside a task. |
task_status | id (optional) | Status of one task or all: running, pausing, paused, done, failed or cancelled, with the iteration, the last marker and the stop reason. |
steer_task | id, text | Adds a message to the task's history. The next iteration sees it; the current one is not interrupted. |