CLI

The site builds this page from the CLI's own help text, so it always matches the version it documents. In a project, run each command from the project root as node_modules/.bin/agentlane <command> or npx agentlane <command>. In Claude Code with the plugin, a bare agentlane works too.

npx agentlane --help        # every command
npx agentlane up --help     # one command
npx agentlane --version

Lanes

Claim, list and release lanes, and clean up the device pool. What a lane holds explains the model behind them.

agentlane claim

Claim a lane for this session and folder: ports, and a pool simulator or emulator. Prints shell exports on stdout: eval "$(agentlane claim)".

agentlane release

Release this session's lane for this folder: stop the services up started (each verified by pid and start time), clear the bundler pin, run the teardown hook, then each resource's teardown. A teardown that fails is kept, and the next release or reap on this Mac tries it again. release <id> releases a lane by id: yours, or one whose owner is proven gone. For a lane that has ended, it runs the teardowns still pending for it.

agentlane status

Every lane on this Mac: owner, folder, start, idle time, last action.

agentlane lanes

--json: the same as status, as JSON for tools.

agentlane touch

Record activity on this session's lane (--action <text>).

agentlane prune

List the pool simulators and emulators no lane holds, 0.2.x's included; --yes deletes them to free their disk. Each deletion takes the registry's lock and checks again that no lane holds the device, so one claimed meanwhile is kept. A device the registry has no record of is never deleted, even one named like a pool device.

Environment

These commands read agentlane.json from the current folder or the ones above it. Bring a worktree up walks through up.

agentlane up

Take this worktree from bare to the running app on its own simulator or emulator, or to its web app's services: preflight, claim, setup, resources, build (through the build cache), services, hygiene, launch, signin, doctor; a web app skips the device steps. Prints shell exports on stdout: eval "$(agentlane up)".

agentlane restart

Stop one of this lane's services and start it again on the same port, with this call's environment: KEY=value agentlane restart api. This is how to change a service's environment (a feature switch, an admin toggle, a client gate) without release and up. The service gets the lane's variables plus this call's environment, as up gives it; a variable passed to up and not to restart is gone. Returns once its ready check passes; the lane, the device, the app and every other service stay as they are.

agentlane setup

Run the project's setup hook in this worktree, without claiming anything (it gets AGENTLANE_WORKTREE and the hook locale only).

agentlane exec

Run one command with this lane's environment: agentlane exec -- <command> [args...] With a driver block, 'maestro' there is the toolkit's build on this lane's device, with JDK 17 and the lane's runner token: agentlane exec -- maestro test <flow.yaml> Without one, or with an invalid config or no running device, 'maestro' says why and runs nothing.

agentlane doctor

Is this worktree's instance worth driving? Checks the lane, toolchain, device, app, launch, services and hygiene, read-only; exit 1 names each fix.

agentlane schema

Print the JSON Schema of agentlane.json.

Driving

Each of these acts on the simulator, emulator or browser that this session claimed for this folder, and never on another lane's. See and drive the app shows them in use.

Each of these takes --worktree <dir> to name the folder whose lane to use.

agentlane look

What's on screen, one line per element.

agentlane run

Run Maestro YAML and print what changed: run <flow.yaml>, run --yaml '<yaml>', or run - (stdin).

agentlane screenshot

Save the screen as a JPEG (a browser's as a PNG) and print its path.

agentlane record

record save <file> writes this session's passing run steps as a flow; record show; record clear.

agentlane evidence

Keep evidence in the lane's evidence folder, which outlives release; each prints what it wrote.

• agentlane evidence screenshot
• agentlane evidence video start | stop
• agentlane evidence trace start | stop
• agentlane evidence logs [--since <n>m|<n>s|<n>h]: services, hooks, driver, device log, browser console
• agentlane evidence list

A failed run, and a failed command under exec, keep their own evidence there on their own.

agentlane driver

driver start | status | stop: the warm Maestro session behind look, run and screenshot. driver install [--from <zip>]: install the pinned Maestro build (first use does this on its own).

agentlane browser

browser install [--driver playwright|agent-browser] [--from <dir>]: install the pinned driver and its browsers into the toolkit's data folder (up does this on its own); browser status.

agentlane device

Controls for the claimed simulator or emulator:

• agentlane device location <lat>,<lon> | clear (clear: simulator only)
• agentlane device permission grant|revoke|reset <service> [<bundle id>]
• agentlane device appearance light|dark
• agentlane device push <bundle id> <payload.json | -> (simulator only)
• agentlane device clipboard set <text> | get (simulator only)
• agentlane device open <url>

agentlane mcp

Serve look, run and screenshot over MCP on stdio (look and screenshot read a browser lane too).

Agent hooks

The hooks that init and the plugin write call these with the hook's JSON on stdin. You don't run them yourself. The device guard and session hooks says what each one does.

agentlane hook

• agentlane hook pre-tool-use: Deny a simctl, adb, emulator or avdmanager command aimed at a device another session holds, and a playwright-cli or agent-browser command aimed at another session's browser, the way the agent's hooks block.
• agentlane hook session-end: Release every lane this session holds and stop their services, in a detached process (the session-end budget is short). Both take --agent claude|codex|cursor|copilot|gemini|antigravity (default claude).

Agents

Install for your agent shows what init writes for each agent, and The skills what each skill does.

agentlane init

• agentlane init [--agents <list> | --all] [--dir <folder>] [--check]

Write each agent's own project files from one source: the toolkit's skills in .agents/skills (mirrored into .claude/skills for Claude Code), the MCP server, and the device guard and session-end hooks. Agents: claude, codex, cursor, copilot, gemini, antigravity. Without --agents or --all, init wires the agents whose files the project has (CLAUDE.md, .codex/, .cursor/, ...) or whose session runs it, and in a terminal asks you to confirm or change them. Where the project's package.json doesn't list agentlane, init adds it as a dev dependency at its own version with the project's package manager, creating a private package.json when there is none, because the hooks and the MCP server run node_modules/.bin/agentlane. Where Claude Code loads the agentlane plugin (the project's or your settings, or the session running init), Claude Code is left to the plugin, and init removes the copies of its skills and hooks an earlier init wrote. A second run changes nothing; a changed file is backed up first, and a file init can't parse is refused, with nothing written. --check writes and installs nothing, and exits 1 when a file would change. The folder defaults to the one with agentlane.json, else the worktree.

agentlane skills

• agentlane skills list: The toolkit's skills, each with what it is for.
• agentlane skills get <name>: Print a skill's content for this installed version; the skill files in a project only point here.

Benchmark

bench measures agentlane on the example app in the agentlane repository. The method is in bench/README.md in the agentlane repository.

agentlane bench

Measure the toolkit on examples/expo-app: cold-cold, cold, warm, relaunch and first interaction, each with read, screenshot, quick tap, tap and a short flow; on the web app's browser lane, warm read, screenshot, click and flow. Writes a dated Markdown report and its JSON.

bench compare <a.json> <b.json>: the two runs' medians side by side.