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