Skip to main content
Preflight uses Facebook idb (iOS Development Bridge) to inject touch events directly into the iOS Simulator through IndigoHID — the same touch event subsystem that real devices use. This means taps, swipes, and long presses happen without your Mac cursor moving at all.

​
Why idb Matters

Without idb, Preflight falls back to Swift CGEvent injection: it maps simulator screen coordinates to macOS screen coordinates and synthesizes mouse events. This works, but it briefly moves your cursor on every tap — disruptive when you’re working alongside the AI agent. With idb, touch events go directly to the simulator process. Your cursor stays wherever you left it.

​
Touch Injection Pipeline

simulator_tap(x=200, y=400)
    │
    ├─ idb available? ──YES──► idb ui tap --udid <UDID> 200 400
    │                           (IndigoHID → real iOS touch event)
    │                           (zero cursor movement)
    │
    └─ idb unavailable? ──► coordinate mapper → macOS screen coords
                             → Swift CGEvent binary → mouse down/up
Preflight checks idb availability once at server startup and caches the result. It searches in this order:
  1. PREFLIGHT_IDB_PATH environment variable (if set)
  2. which idb — respects the PATH in your MCP config
  3. Common install locations (see below)

​
Install idb

1

Tap the Facebook Homebrew repository

brew tap facebook/fb
2

Install idb-companion

This installs the companion daemon that runs alongside the simulator.
brew install idb-companion
3

Install the idb Python client

This installs the idb CLI binary that Preflight calls.
pip3 install fb-idb
4

Verify the installation

which idb
You should see a path like /opt/homebrew/bin/idb or ~/Library/Python/3.11/bin/idb.

​
Finding Your idb Path

pip3 installs idb into a Python-versioned directory that isn’t always on the system PATH. Run: 
which idb
If which returns nothing, check the common pip3 install locations directly: 
ls ~/Library/Python/3.*/bin/idb
Preflight automatically scans these paths at startup:
PathInstall method
/opt/homebrew/bin/idbHomebrew (Apple Silicon)
/usr/local/bin/idbHomebrew (Intel)
~/Library/Python/3.9/bin/idbpip3 (Python 3.9)
~/Library/Python/3.10/bin/idbpip3 (Python 3.10)
~/Library/Python/3.11/bin/idbpip3 (Python 3.11)
~/Library/Python/3.12/bin/idbpip3 (Python 3.12)
~/Library/Python/3.13/bin/idbpip3 (Python 3.13)
~/.local/bin/idbpip3 (user install)
If your path is in this list, Preflight finds idb automatically even without PATH or PREFLIGHT_IDB_PATH.

​
Adding idb to PATH in Your MCP Config

MCP clients launch the server with a minimal environment. You need to explicitly include the directory containing idb in the PATH env var. 
{
  "mcpServers": {
    "preflight": {
      "command": "node",
      "args": ["/path/to/Preflight/dist/index.js"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}
If idb is in a Python bin directory, append it: 
{
  "env": {
    "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/Users/you/Library/Python/3.11/bin"
  }
}
Replace 3.11 with your actual Python version. Run python3 --version to check.

​
Using PREFLIGHT_IDB_PATH

If you’d rather not modify PATH, set PREFLIGHT_IDB_PATH to the absolute path of the idb binary: 
{
  "mcpServers": {
    "preflight": {
      "command": "node",
      "args": ["/path/to/Preflight/dist/index.js"],
      "env": {
        "PREFLIGHT_IDB_PATH": "/Users/you/Library/Python/3.11/bin/idb"
      }
    }
  }
}
Preflight checks this path first. If the file exists, it uses it immediately without scanning other locations.

​
Verifying idb Is Detected

The easiest way to confirm idb is working is to check the tool descriptions returned to your MCP client. When idb is active, interaction tools show [cursor-free] in their description. When falling back to CGEvent, they show [CGEvent fallback]. You can also set LOG_LEVEL=debug to see exactly what Preflight finds at startup: 
[2026-03-25T10:00:00.000Z] [DEBUG] [idb] idb found via PATH: /opt/homebrew/bin/idb
or, if detection fails: 
[2026-03-25T10:00:00.000Z] [DEBUG] [idb] idb not found in PATH or common locations

​
CGEvent Fallback Behavior

When idb is not available, Preflight uses a compiled Swift binary (dist/mouse-events) to inject touch via CGEvent:
  • It maps simulator screen coordinates to macOS display coordinates using the simulator window geometry
  • It synthesizes mouseDown and mouseUp events at the computed screen position
  • Your Mac cursor moves to that position briefly, then stays there
This works for most interactions but is unsuitable if you need to use your Mac while the AI agent is running tests.
The Swift binary (dist/mouse-events) is compiled during npm run build alongside the TypeScript output. If you see errors about the binary missing, run npm run build again — it requires swiftc from Xcode Command Line Tools.

Build docs developers (and LLMs) love

Get started for freeTalk to us