What is warden

warden is an open-source CLI plus e2e framework for iOS, Android and Expo apps. Use it when coding agents, worktrees and CI share one Mac and each needs its own simulator.

warden claim ios --json                  # your agent leases a simulator
warden ui snapshot -i --udid $UDID       # reads the screen as text
warden ui press id=todo-add --udid $UDID # taps, types, waits
warden e2e                               # the saved spec runs on N leased devices

The loop

1. Claim. Your agent leases a simulator or emulator no one else holds.
2. Drive. It runs the app with warden dev and drives it with warden ui: snapshot, tap, type, wait.
3. Verify. It checks the result with wait / is / get, not a screenshot.
4. Keep. It writes what it verified as a *.e2e.ts spec with @delacour/warden-e2e, using the same selectors it drove by hand.
5. Scale. warden e2e runs the suite across N leased devices in parallel.

Underneath, every device, port and app build on the Mac is leased machine-wide. One sqlite registry (~/.warden/warden.db) is shared by every agent session, worktree, repo, CI job and shell. Two claims at the same instant are serialised with BEGIN IMMEDIATE; there are no lockfiles. See How warden works.

What it does

• Leases iOS simulators, Android emulators and TCP ports to one owner at a time.
• Drives a leased device from the command line with warden ui.
• Runs *.e2e.ts specs on the same driver, in parallel, with failure artifacts.
• Picks the specs a git diff needs with warden affected.
• Reuses native builds across worktrees by Expo fingerprint (installed, cache, EAS, local build).
• Queues device boots by host RAM and CPU.
• Never shuts down, erases or installs on a device it did not create or lease.

Who it is for

• Developers using coding agents (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf, Zed) who want the agent to prove its UI change on a real simulator.
• Teams running several agents or worktrees on one Mac, where two sessions would otherwise grab the same simulator or Metro port.
• CI that wants an e2e suite fanned out over several simulators.

Works with

The skill installs into any agent the skills CLI supports. Claude Code and Codex also get a SessionEnd hook that releases what a session leased. See Set up your agent.

Limits

• iOS needs macOS with Xcode. Android needs the Android SDK (adb, emulator).
• A Linux binary exists. Windows is not supported.
• The accessibility tree exposes only accessible views: mark a view accessible and give it a testID to make it targetable.