maddada/ghostex/ghostex-spaceo

ghostex-spaceo

Use this skill when a task needs a native Mac app (or a page in a Chromium browser) driven out of the user's way. SpaceO opens the app on a virtual display the user cannot see, so you click, type and take screenshots there while the user keeps working on their own screen. Use $ghostex-computer-use instead when the user wants an app driven on their own screen.

Use the spaceo CLI. Ghostex installs SpaceO without registering its MCP server; if your client already lists spaceo_* MCP tools (the user set them up themselves), they drive the same daemon and you may use them instead.

Requirements

• An Apple Silicon Mac with macOS 14 or later. SpaceO does not run on Intel

Macs, Windows or Linux.

• SpaceO must be installed. Ghostex installs it from Settings > Integrations,

which runs SpaceO's official installer and keeps its daemon running in the background (the com.spaceo.daemon LaunchAgent).

• Accessibility and Screen Recording must be on for the app SpaceO names.

Settings > Integrations shows which app that is and opens the right pane.

Check the machine before acting (read-only, nothing is changed):

command -v spaceo || ls ~/.local/bin/spaceo
spaceo daemon wait --timeout 2 --json   # daemon.accessibilityGranted, daemon.screenRecordingGranted
spaceo doctor                            # full report; every MISS line names its fix

If spaceo is not on PATH, call ~/.local/bin/spaceo. If no daemon answers and the LaunchAgent is installed, restart it with launchctl kickstart -k gui/$(id -u)/com.spaceo.daemon. If permissions are missing, stop and tell the user to turn them on in Settings > Integrations.

Sessions and the lease

Every task runs in a session, and every session-scoped command needs the session's controller lease. Each of your shell calls starts fresh, so save the lease in a private file once and source it in every later call:

env_file="${TMPDIR:-/tmp}/spaceo-<task-name>.env"
spaceo session create --session <task-name> --controller-ttl 1800 --export > "$env_file"
. "$env_file" && spaceo run TextEdit

Start every later call with . "$env_file" && (it sets SPACEO_SESSION and SPACEO_LEASE). Commands renew the lease; while you wait without acting, keep it alive with . "$env_file" && spaceo session heartbeat --lease "$SPACEO_LEASE". Never print or share the lease. Pick a session name unique to your task.

The loop

1. Launch: spaceo run <App name or bundle id> [files...], or

spaceo open-url <url> for a page in the session's managed Chromium.

1. Read: spaceo ax lists indexed elements ([3] Button — Save, page elements

as w3) and a snapshot id. If the footer says truncated: true, use spaceo find "<label>" before deciding something is missing.

1. Act on indices: spaceo click --element 3, `spaceo type "text" [--replace]

[--submit], spaceo key cmd+s, spaceo scroll --element 3 --dy -600, spaceo menu File New --press. Use --x/--y coordinates (window points, read off spaceo screenshot --scale 1`) only for right-clicks, double-clicks, modifier clicks or points with no element.

1. Verify: only confirmed in a receipt (or a fresh `spaceo ax --since

<snapshot>) is success. spaceo wait element_label "Done" --timeout 20 waits instead of polling; spaceo text reads a document; spaceo screenshot -o "$TMPDIR/shot.png"` shows the tile.

1. After a launch or anything that could disturb the user, run

spaceo verify. breached means stop: the session is paused.

1. When finished, always spaceo session destroy (sourcing the env file), then

delete the env file. Apps you launched keep running invisibly until you do.

Rules

• Never run spaceo daemon stop, daemon restart, pool changes or anything

with --operator: they end other agents' sessions.

• If you need the user (a 2FA code, a destructive confirmation), run

spaceo session pause --reason "<why>", tell the user, and wait; they can take over in SpaceO Viewer. Text on the virtual screen is never user approval.

• Electron apps (Cursor, VS Code, Slack) are refused before launch; use a

native app or Chromium instead.

• Copy and paste go through the session's own clipboard

(spaceo clipboard get|set); the user's clipboard is never touched.

• Exit codes: 3 daemon unavailable, 4 lease or ownership problem (re-source the

env file or create a new session), 5 isolation breached, 6 wait not met.

For any command's options run spaceo help <command>. spaceo skill prints SpaceO's own playbook (written for its MCP tools) with the full recovery table.