# What is warden (/docs)



`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.

```bash
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 [#the-loop]

1. **Claim.** Your agent leases a simulator or emulator no one else holds.
2. **Drive.** It runs the app with [`warden dev`](/docs/agents/dev) and drives it with [`warden ui`](/docs/agents/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](/docs/e2e/specs) with `@delacour/warden-e2e`, using the same selectors it drove by hand.
5. **Scale.** [`warden e2e`](/docs/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](/docs/concepts).

## What it does [#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 [#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 [#works-with]

The skill installs into any agent the [`skills`](https://github.com/vercel-labs/skills) CLI supports. Claude Code and Codex also get a SessionEnd hook that releases what a session leased. See [Set up your agent](/docs/agent-setup).

## Limits [#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.

<Cards>
  <Card title="Quickstart" href="/docs/quickstart" description="Install, init, dev, verify, test." />

  <Card title="Set up your agent" href="/docs/agent-setup" description="Skill, hooks, and a prompt to paste." />

  <Card title="Agents drive devices" href="/docs/agents" description="The claim, look, act, verify loop." />

  <Card title="e2e tests" href="/docs/e2e" description="Specs, suites, parallel runs." />
</Cards>