Skip to content

Commands

Agents use Offstage through MCP or the offstage command. Both do the same things. Every command answers with one result: confirmed, failed or refused, and why.

Connect your agent

Offstage connects to Claude Code, Codex or Cursor during setup. Or run this, look at the change it shows, then add --apply:

offstage setup

Then ask your agent in plain words, for example: “Use Offstage to open my app and check the sign-up screen.”

Everyday commands

Most testing needs only these. Offstage creates and closes the workspace for you.

offstage open <app>
Open any app out of sight and look at it.
offstage look
A screenshot, plus the labels of everything you can click or read.
offstage click <label>
Click a control by its label, and check what appears.
offstage type [<label>] <text>
Fill in a text field, then read it back.
offstage assert <text>
Check that something is on screen, or that it’s gone.
offstage wait-for <text>
Wait until something appears or disappears.
offstage done
Close the workspace. Apps Offstage opened there are asked to quit.

Workspaces

offstage create
Make a workspace: a private screen. Set its size, name and how long it lasts.
offstage list
All workspaces and what’s in them.
offstage inspect <ws>
One workspace and everything that happened in it.
offstage rename <ws> <name>
Give a workspace a new name.
offstage pause <ws> · resume <ws>
Stop and restart agent actions in a workspace.
offstage close <ws> · --all
Close one workspace, or all of them.
offstage recover <id>
After an unexpected stop, move surviving apps into a new workspace.

Apps

offstage launch <ws> -- <command>
Start an app or command in a workspace, without bringing it to the front.
offstage run -- <command>
Run something that finishes on its own, such as a test, in a temporary workspace.
offstage wait <pid>
Wait for an app Offstage started to finish.
offstage capabilities
What Offstage has checked works in each app.

Looking

offstage screenshot <ws>
A picture of the workspace, or of one window.
offstage windows <ws>
The windows in a workspace.
offstage view <ws>
Open a live view, so you can watch.

Precise control

offstage ui tree <ws>
Every control in the workspace’s apps, with an id for each.
offstage ui find <ws>
Find controls by type, text or identifier.
offstage ui read <ws> <element>
Read a control’s text.
offstage ui wait <ws>
Wait for a control to appear or disappear.
offstage ui press · focus · menu <ws> <element>
Press a control, focus it, or open its menu.
offstage ui set <ws> <element> <value>
Set a control’s value, then read it back.
offstage ui key <ws> <element> <key>
Send one key to one app, where Offstage has checked that this is safe.

Setup

offstage setup
Show what connecting Offstage to Claude Code and Codex would change, then do it.
offstage status
Whether Offstage is running, its permissions and its workspaces.
offstage check
Test Offstage on this Mac.
offstage guide · skill
A short guide for agents, and the Claude Code skill.
offstage settings
Your preferences. Change them in the menu bar.
offstage mcp
The MCP server. Agents start this for you.

MCP tools

The same features, for agents that use MCP. 34 tools in all.

offstage_open
Open an app out of sight and look at it.
offstage_look
A screenshot, plus the labels of what’s on screen.
offstage_click
Click a control by its label.
offstage_type
Fill in a text field by its label.
offstage_assert
Check that something is on screen now.
offstage_wait
Wait for something to appear or disappear.
offstage_done
Close the workspace.
offstage_status
Version, permissions and workspaces.
workspace_create · list · inspect
Make, list and inspect workspaces.
workspace_pause · resume · close
Pause, resume and close workspaces.
workspace_screenshot · windows
Pictures and windows of a workspace.
workspace_view
Open a live view for you. Only when you ask.
workspace_recover
Recover apps after an unexpected stop.
app_launch · app_run · process_wait
Start apps and commands, and wait for them.
app_capabilities
What Offstage has checked works in each app.
ui_tree · ui_find · ui_read · ui_wait
Find and read controls precisely.
ui_press · ui_set · ui_focus · ui_menu · ui_select
Use controls precisely, with each result checked.
ui_key · ui_scroll · ui_drag
Keys, scrolling and dragging for one app you opened, never your keyboard or mouse.

Results

confirmed
It happened, and Offstage saw it happen.
unconfirmed
It was done, but Offstage couldn’t see the change. Say what to expect next time.
failed · timed_out
It didn’t work. The result says why, and what to try next.
refused · unsupported
Offstage won’t do it here, for example in a paused workspace.

Run offstage --help for every option.