Ghost — invisible, non-interfering, fast computer use

Verified end-to-end (21/21 cross-app test suite: TextEdit, Stickies, System Settings, Finder, live concurrency).

Four guarantees:

1. Invisible — the app runs hidden; Fletcher never sees it. AX driving and pixel capture both work on a fully hidden app (visible=false).
2. No hijack — cursor never moves, apps never hidden from him, machine never locked, his visible Space never switches.
3. No interference — input is written straight into the target UI element via the Accessibility API (no synthetic keystrokes, no focus change). He can type into his own app at the same time; verified zero cross-contamination.
4. Fast — AX reads/actions ~0.2–0.3s each; native open→read→close ~2–3s; no screenshot→reason→click loop.

The engine is ghost-ax (~/.claude/skills/ghost/bin/ghost-ax), a focus-free AX tool over already-trusted System Events (no new permission prompt, ever), plus Peekaboo for visual element discovery, plus a headless browser for the web.

Routing — pick the fastest surface

• Web / browser → mcp__ghost-web__* (headless, isolated Playwright). A separate browser he can't touch; open→read→close in ~1–2s. Use for "open X and look at it", scraping, web forms. Never drive a browser via AX/pixels.
• Native macOS apps → ghost-ax + Peekaboo (below).
• Never the built-in computer-use unless he explicitly says "use the real computer-use / take my screen".

Run an app INVISIBLY (he never sees it)

1. Open hidden:
   • Existing file / content: ghost-ax open "<App>" "/path/file" → fully invisible, no flash. (Reading an already-running app is also invisible.)
   • To create NEW content invisibly in a document app: write a temp file and open it (printf ... > /tmp/x.ext; ghost-ax open "<App>" /tmp/x.ext). This avoids the new-window flash entirely.
   • Bare ghost-ax open "<App>" launches hidden and force-hides repeatedly; good for apps you'll only read/act on.
2. New windows: creating a brand-new window (File ▸ New) briefly forces the app visible. Two fixes: prefer opening files / the temp-file trick (no flash); OR use the off-screen stage — ghost-ax stage "<App>" moves every window onto the invisible virtual display, so windows render off your monitor even when created. After a new window, ghost-ax hide or re-stage. The stage is the zero-flash path for non-file apps (Settings/Calculator).
3. Act (all focus-free, invisible) — see commands below.
4. Close: ghost-ax quit "<App>".

ghost-ax command reference (focus-free, no prompt, never reveals the app)

Lifecycle: open "<App>" [file] · hide "<App>" · quit "<App>" Off-screen stage (the virtual display — already set up): ensure-display · stage "<App>" (moves all the app's windows onto the invisible virtual display, dead-centre so macOS won't clamp them back) · shot "<App>" [path] (capture the window) Input:

• type "<App>" "<text>" — insert at the caret of the app's text field (auto-targets the right field)
• return|tab|clear "<App>"
• set "<App>" "<role>" "<title>" "<value>" — set a control (checkbox 1/0, slider number, field text, popup)
• press "<App>" "<title>" — focus-free click (AXPress) of a button/link/checkbox
• action "<App>" "<title>" "<AXAction>" — any AX action (AXPress,AXIncrement,AXDecrement,AXShowMenu,AXScrollToVisible,AXConfirm,AXCancel,AXRaise)
• reveal "<App>" "<title>" — scroll an element into view
• focus "<App>" "<role>" "<title>" — focus a field without raising the app
• menu "<App>" "<TopMenu>" "<Item>" ["<SubItem>"] — invoke a menu-bar item via AX (focus-free; Peekaboo's own menu steals focus, this one doesn't) Read (safe):
• read "<App>" — text of the focused/main field · get "<App>" "<role>" "<title>" — a specific element's value
• exists "<App>" "<role>" "<title>" → 1/0 · wait "<App>" "<role>" "<title>" [sec] — block until it appears (use instead of sleeping)
• dump "<App>" — list every element as a label line, to discover exact titles/roles

Match rules: role = substring of the AX role (AXTextArea,AXButton,AXCheckBox,AXSlider,AXPopUpButton,AXTextField…), "" = any role. title = substring of title/description/value, "" = any. Success prints ok:...; failure prints ERR: ... to stderr and exits non-zero.

Discovering what to click

ghost-ax dump "<App>" (focus-free) or peekaboo see --app "<App>" --json (richer: element IDs + bounds, visual). Use these to get exact titles, then feed press/set/type.

Performance (measured)

AX ops are fast: type/read/exists/wait ~0.2s, press/set ~0.3–0.7s (walks the tree), stage ~0.16s (coord cached in ~/.peekaboo/ghost-stage). The matcher reads only role/title/description (never AXValue — that copies whole text areas and was a 2.4s→0.7s regression). The slow lanes are: app launch ~1–1.5s (macOS floor) and any peekaboo call ~0.5–0.6s startup — so use ghost-ax (AX) over peekaboo wherever possible, and never sleep when a ghost-ax wait will do. For pixel-fallback apps (Calculator) each peekaboo click is ~0.6s; batch with peekaboo run if doing many.

Lightning-fast recipe

• Web: mcp__ghost-web__* navigate → snapshot/evaluate → close (~1–2s).
• Native: ghost-ax open → wait for the key element → act → read/peekaboo image → quit. Use wait, never fixed sleeps; AX reads over pixel screenshots.

Isolation — he can't interfere even if he tries

• AX input writes directly into the element and ignores the global keyboard/cursor — his typing on his own Space can't collide (proven concurrently).
• Hidden app = no window on his screen to touch. Headless ghost-web browser = separate process, untouchable.
• Virtual display (set up — the full "screen-share" model): BetterDisplay is installed and set to launch hidden at login; a "GhostDisplay" virtual screen renders off the physical monitor. ghost-ax ensure-display creates/connects it on demand (auto-launches BetterDisplay if needed); ghost-ax stage "<App>" moves the app's windows there; capture with ghost-ax shot or peekaboo image --screen-index 1. No permission grant was needed. This is the zero-flash-ever surface for non-file apps, and the place to do the rare pixel-coordinate click (off his physical screen).

Known limits (honest)

• Process name ≠ app name for some apps. ghost-ax targets the process name (as in Activity Monitor / System Events). Most match (Notes, TextEdit, Finder, Safari, Music, Messages, Maps…); a few differ (e.g. "Visual Studio Code" → process "Code", "Microsoft Word" stays "Microsoft Word"). If a command says "no window", check the process name with osascript -e 'tell application "System Events" to name of every process'.
• Icon/symbol buttons (e.g. Calculator's keypad) and some custom/canvas UIs aren't name-addressable via AX → use peekaboo see element IDs, or pixel-coordinate clicks scoped to a parked off-Space window (those briefly take focus — keep the window off his Space).
• Rich-text content reading (Stickies/RTF) can return empty from read; typing/acting still works — verify visually with peekaboo image if needed.
• Multi-window apps: ghost-ax acts on the front window (window 1).
• Minimising a window can disrupt its AX tree briefly; un-minimise before dumping.

Reference

• mcp__ghost__* (Peekaboo) and mcp__ghost-web__* (headless Playwright) are pre-allowlisted and load on Claude Code startup; ghost-ax works immediately via Bash. All three MCP servers verified Connected.
• Accessibility + Screen Recording already granted. ~/.peekaboo/config.json: captureFocus: background, savePath: ~/.peekaboo/captures (no Desktop litter).
• Peekaboo 3.x beta: if a Peekaboo flag is rejected, run peekaboo learn or peekaboo <cmd> --help.