agentlane

agentlane gives each agent session a lane: its own ports, dev servers and database, and its own iOS simulator, Android emulator or browser, with fast tools to see the app and drive it. Agents use it through the agentlane CLI, an MCP server (look, run, screenshot), and skills and hooks that teach them the loop. It works with Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and Antigravity, on web apps, iOS and Android.

1. In your project's root:

npx agentlane init

2. Then tell your agent:

Set this project up with agentlane.

init wires the agents it finds and adds agentlane to your dev dependencies. Setup then learns how your project runs and brings each app up in its own lane. Getting started walks through both steps.

Why agentlane

• Every agent, one install. Six agents get the same CLI, MCP server, skills and hooks from one init.

• Web, iOS and Android in one tool. look, run and screenshot work the same on a simulator, an emulator or a browser.

• The whole environment, per agent. Ports, dev servers, a database, sign-in, and a device or browser that no other agent touches.

• Fast. A warm lane reads the screen in about 0.15 s. See Speed.

• It checks the app before your agent trusts it. doctor confirms that every server runs this worktree's code, and names the fix when one doesn't.

• Evidence you can open. Videos, traces, logs and screenshots, plus the Maestro flows and Playwright tests your agent commits.

• It cleans up. When a session ends, its lane is released: services stop, databases are torn down, and devices go back to the pool.

• Local. No account, no hosted service, no telemetry of its own.

Related MCP server: pagelens

Speed

What makes it fast:

• A warm Maestro session. look, run and screenshot talk to a Maestro session that stays up between calls, so only the first call pays to start it.

• A runner port per session. Stock Maestro gives every iOS simulator's runner the same port, 22087, so with two simulators the second one started cold on every call: 6.5 s per screen read, against 0.12 s with our patch.

• Quick taps. On Android, run --quick skips Maestro's fixed 750 ms window settle and the screen reads after the tap.

• A build cache your worktrees share. The example app's iOS build took 91.5 s. A fresh worktree got its build from the cache in 6.5 s and reached the running app in 38.6 s.

• A device pool. Lanes reuse simulators and emulators instead of creating new ones, and emulators boot from their Quick Boot snapshot in 1.6 to 1.8 s, against 14.6 s for a cold boot.

Speed on the docs site explains each one.

All on an Apple M4 Max with 48 GB of memory.

• iOS column: agentlane bench on the example app, two iPhone 17 simulators alternating, release 0.1.3 with the Maestro build agentlane installs (2.11.0-agentenv.3). The Mac was under memory pressure, so these are upper bounds.

• Browser column: the same bench on the example's web app, Playwright 1.64.0 with Chrome for Testing, a 0.2.0 development build.

• Port comparison: 16 reads per simulator on another app, stock Maestro 2.8.0 against an early build with the port patch.

• Build cache: single runs of 0.2.0 on the example app. Boot times: two boots each of a Pixel 8 emulator on Android 36.

bench/README.md has the method, and agentlane bench runs it on your machine.

What a lane gives your agent

Its own environment

• Ports from a registry on the machine, with your dev servers started on them and checked ready before up returns.

• A database, or any resource you declare, created for the lane and torn down when it ends, after a crash too.

• Sign-in through your project's hook, so the app opens signed in.

• A simulator, emulator or browser from a pool. When the pool is full, the request waits for a free device.

• restart changes one service's environment, such as a feature flag, without tearing the lane down.

Eyes and hands

• look reads the screen or page, one line per element, and --interactive keeps only what can be tapped or typed into. On iOS, our Maestro patch puts each element's type in the hierarchy to make that possible.

• run runs Maestro steps and prints what changed.

• In the browser, Playwright's playwright-cli (the default) or agent-browser, run through agentlane exec.

• record save turns the session's passing steps into a Maestro flow you can commit.

• device sets location, permissions, appearance, push notifications, the clipboard and links to open.

• Before launch, up sets the device's location, status bar and keyboard, so captures match from run to run.

Evidence and housekeeping

• evidence keeps videos, Playwright traces, logs and screenshots in a folder that outlives the lane. A failed run or exec command keeps its own.

• A hook denies simctl, adb, emulator, avdmanager, playwright-cli and agent-browser commands aimed at another lane's device or browser.

• The next lane taken on the machine cleans up any lane whose session died, and prune deletes pool devices no lane holds.

The skills

The skills teach an agent the whole loop in your project, from setup to proof. Each stub init writes prints its skill from the installed version, so the skills update with the package.

• setup finds how your project runs its apps, servers, data and sign-in, wires your agents, writes agentlane.json, and brings each app up until doctor reports ready. It asks you only what it can't find out.

• dev-loop is what an agent follows whenever it runs the app: one lane per session, up, doctor before trusting an instance, release when done, and what counts as proof.

• drive covers driving the lane's device or browser, turning what worked into a committed flow or test, and keeping evidence.

• create-verification-skill writes your project's run skill, with how to launch, check, drive and capture the app and a page per user-facing feature, and runs it end to end once before it is done.

• maintain-verification-skill keeps the run skill and its feature pages true as the app changes. It checks each page against the code, drives each feature, and opens at most one PR of corrections.

Claude Code can load the skills, the MCP server and the hooks as the agentlane plugin, and Codex, Cursor and Gemini CLI have plugins with the skills and the MCP server.

Once setup reports ready, any agent in the project can take work like this:

Add a "clear completed" button to the list. Bring the app up on iOS and on the web, prove the button works with a Maestro flow and a Playwright test, and record a video of it.

Where it runs

agentlane needs Node 24 or newer, and Xcode or the Android SDK for mobile apps. It drives simulators, emulators and browsers, not physical devices. On Linux, Chrome needs system libraries that agentlane can't pin; agentlane doctor names any that are missing and gives the command that installs them. Where it runs on the docs site lists what each platform needs.

Security and telemetry

agentlane runs on your machine. It has no account, no hosted service and no telemetry of its own.

• On first use it downloads its pinned tools: the patched Maestro from this repository's releases, Playwright and agent-browser from npm, and Chrome for Testing. It checks each against a hash pinned in the package.

• The patched Maestro has its update check, error reporter, screen report and PostHog analytics removed. A check in maestro/test/ calls every local Maestro tool and sees no connection leave the machine. Maestro's cheat_sheet and cloud tools still call Maestro's servers, as they are built to.

• Each lane's iOS runner answers only requests that carry the lane's token, so another process can't drive your simulator through it.

• Playwright and agent-browser run as their maintainers publish them; agentlane doesn't change what they send.

• What your agent reads through look and screenshot goes to the model it runs on, like any tool output.

To report a vulnerability, see SECURITY.md.

Acknowledgements

agentlane is built on these projects, and we're grateful to their authors:

• Maestro drives every simulator and emulator. agentlane ships it with the patches in maestro/.

• Playwright drives the browser by default, on Chrome for Testing.

• agent-browser is the other browser driver a lane can run.

• pstack, Lauren Tan's skills for Cursor, is where dev-loop and the two verification skills began. Parts of them are adapted from it under the MIT licence.

Other projects worth knowing, from people working on the same problem:

• agent-device by Callstack: mobile automation for agents through a CLI, an MCP server and a Node.js API, on more platforms than agentlane covers.

• MobileBuildMCP by Sentry, formerly XcodeBuildMCP: an MCP server and CLI with tools for agents working on iOS and macOS projects.

• The simulator and browser panes in Claude Code Desktop, and the built-in browser Codex uses in the ChatGPT desktop app, which put the running app next to the conversation.

The Android robot in the animation is Google's, used under CC BY 3.0.

Documentation

The docs site has per-agent setup, the config and CLI reference, platform requirements and troubleshooting, with an llms.txt for agents. examples/expo-app/ is the app agentlane is tested on, and CHANGELOG.md lists every release.

License

MIT. The patched Maestro is Apache-2.0; maestro/ holds its patches and notice.

Made by North Star.