Let AI agents see, tap, type, swipe, and visually diff your React Native app.
_{Works with Claude Code · Cursor · Gemini CLI · Codex · any agent that runs shell commands}

---

Install driftx, connect your agent, and it can see and interact with your running app on iOS simulators and Android emulators. Your agent discovers driftx automatically.

What you can do

Ask your agent things like:

• "Make this screen match the Figma" - compare a design mockup against the running app, then fix the differences
• "The login button is cut off, why?" - agent sees the issue, inspects the component tree, and fixes the layout
• "What components are on this screen?" - inspect the full hierarchy with testIDs, bounds, and props
• "Run an accessibility check on this screen" - audit for contrast, labels, and touch target sizes
• "Walk through the onboarding flow and screenshot each step" - navigate, interact, and capture along the way
• "Compare this against yesterday's build" - detect visual regressions between builds

Quick Start

1. Install

npm install -g driftx

2. Connect your agent

Claude Code

driftx setup-claude

Restart Claude Code. The driftx skill is now available.

Fallback - if the command above doesn't work, tell Claude Code:

Fetch and follow instructions from https://raw.githubusercontent.com/nomanr/driftx/main/.codex/INSTALL.md

Verify with driftx doctor, then close and restart the chat.

Cursor

Tell Cursor:

Fetch and follow instructions from https://raw.githubusercontent.com/nomanr/driftx/main/.cursor/INSTALL.md

Verify with driftx doctor, then close and restart the chat.

Gemini CLI

Tell Gemini:

Fetch and follow instructions from https://raw.githubusercontent.com/nomanr/driftx/main/.gemini/INSTALL.md

Verify with driftx doctor, then close and restart the chat.

Codex

Tell Codex:

Fetch and follow instructions from https://raw.githubusercontent.com/nomanr/driftx/main/.codex/INSTALL.md

Verify with driftx doctor, then close and restart the chat.

Other agents

Any agent that runs shell commands can use driftx. Add this to your agent's system prompt:

You have access to `driftx` for seeing and interacting with mobile apps:
- driftx capture -o screenshot.png                    # capture a screenshot
- driftx inspect --json                               # get the component tree
- driftx tap "Button Text"                            # tap by text, testID, or name
- driftx type input-id "text"                         # type into a field
- driftx swipe up                                     # swipe gestures
- driftx compare --design design.png --format json    # compare against a design
Always capture a screenshot after interactions to verify the result.

3. Verify

driftx doctor

Checks that Metro, adb, xcrun, and your simulators are ready.

Commands

# See: capture screenshots and inspect the component tree
driftx capture -o screenshot.png
driftx inspect --json

# Interact: tap, type, swipe, navigate
driftx tap "Login"                        # by text
driftx tap login-btn                      # by testID
driftx tap 150,300 --xy                   # by coordinates
driftx type email-input "user@test.com"
driftx swipe up
driftx swipe down --distance 200
driftx go-back
driftx open-url "myapp://profile/123"

# Compare: diff against designs, audit accessibility, detect regressions
driftx compare --design mockup.png --format json
driftx compare --design mockup.png --with a11y --format json
driftx compare --baseline --format json

# Utilities
driftx devices
driftx doctor
driftx init

Flags

Flag	Description
-d, --device <id>	Device ID or name (picker shown if multiple)
--bundle-id <id>	iOS bundle identifier (auto-detected from Metro)
--verbose	Debug logging
--format <type>	terminal, markdown, or json
--copy	Copy output to clipboard

Requirements

• Metro bundler running (npx react-native start)
• Android: adb available, emulator booted
• iOS: xcrun simctl available, simulator booted

How It Works

Tap resolution uses a 4-tier fallback: CDP fiber tree → XCUITest companion hierarchy → accessibility element query → fiber measurement via measureInWindow().

iOS companion is a pre-built XCUITest server that auto-launches on the simulator. Ships in the npm package, no Xcode build step required.

Visual analysis compares screenshots pixel-by-pixel against design images, runs accessibility checks, and detects layout regressions between builds.

Platform Support

Platform	Emulator/Simulator	Physical Device
Android	Supported	Not yet
iOS	Supported	Not yet

Configuration

driftx init

Creates .driftxrc.json:

{
  "platform": "react-native",
  "metroPort": 8081,
  "threshold": 0.1,
  "diffThreshold": 5
}

Development

npm install
npm run dev          # watch mode
npm test             # run tests
npm run build:ios    # rebuild iOS companion

License

MIT