# agentlane: Every coding agent gets its own running copy of your app

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.

Works with Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity.

## Start in your project

1. Run this in your project:

   ```sh
   npx agentlane init
   ```

2. Then ask your agent:

   > Set this project up with agentlane.

## Why agentlane

- **Every agent, one install.** Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and Antigravity get the same CLI, MCP server, skills and hooks from one [`init`](docs/install.md).
- **Web, iOS and Android in one tool.** [`look`, `run` and `screenshot`](docs/drive.md) work the same on a simulator, an emulator or a browser.
- **The whole environment, per agent.** [Ports, dev servers, a database and sign-in](docs/lanes.md), and a device or browser that no other agent touches.
- **Skills that teach the loop.** [Six skills](docs/skills.md) take an agent from setting the project up to proving a change with a committed flow or test.
- **It checks the app before your agent trusts it.** [`doctor`](docs/doctor.md) 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](docs/evidence.md), plus the Maestro flows and Playwright tests your agent commits.
- **It cleans up.** When a session ends, [its lane is released](docs/guard.md): services stop, databases are torn down, and devices go back to the pool.
- **Local.** No account, no hosted service, and [no telemetry of its own](docs/faq.md#does-agentlane-send-anything-off-my-machine).

## Fast where agents spend their time

- **0.15 s** to read an iOS screen on a warm lane
- **0.16 s** to read a page in the lane's browser
- **6.5 s** to get an iOS build from the shared cache, against 91.5 s to build it

The reads are medians of 16 calls and the build is a single run, all on an Apple M4 Max. [How these were measured](docs/speed.md#how-these-were-measured).

## Start

- [Getting started](docs/getting-started.md): One command in your project, then one sentence to your agent.
- [Install for your agent](docs/install.md): What init detects, installs and writes for each agent, and the Claude Code plugin.
- [Where it runs](docs/requirements.md): Hosts, platforms and the tools each platform needs.

## How it works

- [What a lane holds](docs/lanes.md): Ports, a device or browser, data and processes, claimed per session and folder.
- [How setup decides](docs/setup.md): What the setup skill reads, asks and writes.
- [The CLI, the MCP server and the plugins](docs/parts.md): Which part an agent uses for what.
- [The skills](docs/skills.md): `setup`, `dev-loop`, `drive` and the verification skills: how an agent learns the project.
- [What makes it fast](docs/speed.md): A warm driver, a patched Maestro, a shared build cache and a reused device pool.

## Features

- [Bring a worktree up](docs/up.md): `agentlane up`, from a bare worktree to the running app.
- [Ports and dev servers](docs/services.md): Each service gets a free port and a ready check.
- [Simulators and emulators](docs/devices.md): A pool of simulators and emulators, one per lane.
- [Browsers for web apps](docs/browsers.md): Each web lane gets its own browser profile and driver session.
- [A database per lane](docs/resources.md): Give each lane its own copy of the data, created by up and dropped at release.
- [See and drive the app](docs/drive.md): `look`, `run`, `screenshot` and `record`, on a device or in a browser.
- [Evidence](docs/evidence.md): Screenshots, video, traces and logs that outlive the lane.
- [Doctor](docs/doctor.md): Is this instance worth driving? Read-only checks, each with its fix.
- [The build cache](docs/build-cache.md): One build per set of inputs, shared by every worktree.
- [The device guard and session hooks](docs/guard.md): Hooks that keep agents off each other's devices and browsers.

## Reference

- [CLI](docs/cli.md): Every command and flag.
- [MCP server](docs/mcp.md): The `look`, `run` and `screenshot` tools over MCP.
- [agentlane.json](docs/config.md): The config file, field by field.
- [Environment variables](docs/environment.md): What a lane exports, and the settings you can set.
- [Troubleshooting](docs/troubleshooting.md): Common failures and their fixes.
- [Questions](docs/faq.md): Physical devices, what leaves your machine, Linux, monorepos, CI and cost.
- [Honorable mentions](docs/acknowledgements.md): The projects agentlane builds on, and the ones it works beside.

## Changelog

[Every release](changelog.md)