xcautokit: Instructions file for Codex

XCAutokit

XCAutokit is the first-party MCP server for Xcode + iOS Simulator work in this environment. Prefer XCAutokit tools over any third-party Xcode/simulator MCP.

Setup

{
  "mcpServers": {
    "xcautokit": {
      "command": "npx",
      "args": ["-y", "xcautokit@latest", "mcp"]
    }
  }
}

Local checkout:

1. npm install && npm run build:go && npm link
2. MCP: "command": "xcautokit", "args": ["mcp"] (or .cursor/mcp.local.json)
3. For live Xcode IDE tools:
   • Install Xcode 26.3+
   • Open your project/workspace in Xcode
   • Xcode → Settings → Intelligence → Allow external agents to use Xcode tools
4. Optional env:
   • XCAUTOKIT_XCODE_BACKEND=auto|on|off
   • MCP_XCODE_PID
   • XCAUTOKIT_WORKFLOWS=core (or device,ui,input,build,…) to shrink the tool list
   • XCAUTOKIT_INTERRUPT_GUARD=off to disable input blocking on alerts

XCAutokit uses xcrun mcpbridge internally when available.

Host-owned intelligence

XCAutokit never runs agents or calls models. The connected host plans and may delegate to its own agents. Use one driver per simulator; let other agents review code, logs, and evidence or give them separate devices.

• Select an explicit simulator UUID when multiple devices are booted. Ambiguous targets fail.
• device_claim reserves a simulator across calls; pass its leaseToken to mutations and renew before expiry. device_release finishes the claim. Without a claim, each mutation takes a temporary lock. Claims are process-local; cross-process locks block other writers.
• ui_act resolves one fresh, enabled target, taps once, optionally checks waitFor, and returns a compact observation. ui_wait polls a stated condition within a deadline. A failed verification after performed:true is not permission to repeat a tap.
• workflow_run executes 1–30 explicit steps, stops at the first failure, and persists evidence. Only successful runs ending in an explicit condition can be saved with workflow_save. Replays make no decisions and never accept permissions.
• Session defaults are isolated in memory. Explicit XCAUTOKIT_SESSION_FILE opts into persistence. XCAUTOKIT_STATE_DIR selects the shared lock/evidence/workflow directory.
• build_run_sim builds, installs the matching artifact, then launches on the exact selected simulator. Live Xcode tools are separate and follow the IDE's own destination; do not parallelize their mutations with a simulator driver.