Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

setup

setupTOOL
Open the setup window: connect a new iPhone over USB and Bluetooth, step by step
For a person, not an agent: shows Sign in with Google first (once per Mac), then permissions (Allow Camera and Allow Bluetooth buttons), then one step at a time (plug in, trust, unlock, pair over Bluetooth) and updates by itself every second. The Mac is discoverable over Bluetooth only while this window shows the pairing step. When the iPhone is ready it offers a prompt to copy for an agent.
  • Agents: run this when the user wants to connect a new iPhone, or when list or an error shows no iPhone, an untrusted one, or a Bluetooth link that never connects. A locked iPhone that is trusted and paired needs unlock or the user, not setup. Tell the user to complete setup in the small Ghosthand window. All window actions are user-only; do not interact with it. Poll ghosthand setup status every 2 seconds until ready is true. Continue automatically. Do not retry input or reopen setup while waiting.
  • Do not open it when an iPhone already works, or twice in a row.
  • The daemon runs as Ghosthand.app, so permissions belong to Ghosthand, not your editor. Normal commands never show permission dialogs or open System Settings. Only user clicks in setup request permissions or open settings.
  • The first setup adds the daemon to Login Items (LaunchAgent ~/Library/LaunchAgents/com.remorses.ghosthand.daemon.plist), so it starts at login and after a crash. macOS may show a "Background Items Added" notification. A running daemon is kept. The user can turn it off in System Settings > General > Login Items; setup never turns it on again. Without it, commands still start the daemon on demand.
  • In a sandboxed agent shell (Codex default), run setup with sandbox escalation: the sandbox blocks Launch Services. Never add --foreground: the app and daemon start outside the agent's process, so restarting the agent does not stop them.
  • --permissions keeps the permissions checklist open even when access is already allowed. It never requests permission by itself. Detaches at once, so the terminal is free and the window stays open after the command exits. dashboard and setup share one process: running either again shows its window. Starts the daemon when needed.
CLI flags in this text are arguments: --permissions = permissions
Examples (arguments): {}
Parameters
mac?string
Mac slug from list, e.g. "studio". Needed when several Macs are online
permissions?boolean
Show the permissions checklist even if access is allowed. Opens the app only; only user clicks request dialogs.
Request example
{
  "method": "tools/call",
  "params": {
    "name": "setup",
    "arguments": {
      "mac": "string",
      "permissions": true
    }
  }
}