agentlane 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,61 @@
2
2
 
3
3
  Newest first.
4
4
 
5
+ ## 0.6.0
6
+
7
+ The server a project's lane databases live in can now be declared under `shared` in `agentlane.json`. It runs while a lane needs it and stops 5 minutes after the last one parks or ends, with its data kept. `up --no-app` gives tests a lane with the project's data and nothing else. The guard denies a `docker` or `podman` command that would leave a container running after the agent, and `exec` stops its command once the process that ran it is gone. This version runs beside 0.5.x on the same Mac; "Sharing a Mac with 0.5.x" lists what 0.5.x does differently.
8
+
9
+ ### Moving from 0.5.x
10
+
11
+ 1. **Run `init` again in each project, and commit what it changes.** `node_modules/.bin/agentlane init`, with the agents the project uses, rewrites the guard hooks so they start the toolkit for commands that name `docker` or `podman` too. Until then the container guard doesn't run in that agent, and `doctor` warns that the hooks are stale. Codex asks you to trust the changed hooks again with `/hooks`. The Claude Code plugin's hooks update with the plugin.
12
+ 2. **Declare the database server under `shared`.** Give it a `start` that starts the server and exits, a `stop` that stops it and keeps its data, and a `ready` that exits 0 when it answers. `start` and `stop` must each cope with running twice and with finding the server already in the state they set. The docs' new page, A server the lanes share, has a Docker Postgres to copy. A server you started by hand is found running at the first `up` and kept, and from then on agentlane stops it once no lane needs it.
13
+ 3. **A project that starts its server in a precondition**, such as one that runs `just local-db`: move the command into the shared service's `start`, and leave the precondition to check state only, such as `docker info >/dev/null 2>&1` with "start Docker Desktop" as its fix, or remove it. A precondition never starts a server: it runs before every `up`, and nothing stops what it starts.
14
+ 4. **A project that starts its server in a resource's `create`**, such as a `scripts/lane/db.sh` that runs the container with `--restart unless-stopped` and whose teardown starts the container again to drop the lane's database: take the server start out of both `create` and `teardown`, so they only create and drop the lane's database, and put it in the shared service's `start`. agentlane starts the shared service before each `create` and each teardown that needs it.
15
+ 5. **Drop restart policies.** A container with `--restart unless-stopped` or `restart: always` comes back whenever Docker starts, with no lane that needs it. Remove the policy from `start` and from compose files, and clear it on a container that already has one with `docker update --restart no <container>`.
16
+ 6. **Name the server in `needs`.** Each resource and service that uses it lists it: `"needs": ["postgres"]`. A resource without `needs` doesn't start the server before its `create`, and a lane whose resources and services name none doesn't keep it up.
17
+ 7. **Make test databases resources.** Each database the project's tests create, a test-only one included, becomes a resource that exports its URL (`TEST_DATABASE_URL`, say) and needs the server. Run the tests with `node_modules/.bin/agentlane up --no-app` and `node_modules/.bin/agentlane exec -- <test command>`, and change the run skill's test steps to match. The `setup` and `create-verification-skill` skills write configs this way.
18
+ 8. **Move every branch that has a running lane.** A lane on a branch whose `agentlane.json` has no `shared` records no need for the server, even while it uses it. Once a lane on a moved branch finds the server running and keeps it, agentlane stops the server 5 minutes after that lane parks or ends, under the lane on the older branch. Before you rely on the stop, merge the `shared` config into every branch that has a lane, or run `release` in the lanes on the branches you don't move.
19
+
20
+ ### Sharing a Mac with 0.5.x
21
+
22
+ - **One registry, still format 1.** This version adds the tables `shared_services` and `shared_needs`, and the columns `repository` and `needs` to `resources`, which 0.5.x doesn't read. 0.5.x keeps working on the file.
23
+ - **0.5.x refuses `shared` and `needs`.** Its schema allows neither, so a worktree still on 0.5.x fails validation on a config that uses them. Move a project to `shared` once its branches run this version.
24
+ - **0.5.x starts and stops no shared service.** A lane that 0.5.x parks or ends doesn't count as no longer needing its shared services. The next sweep of this version finds them running with nothing that needs them and stops them 5 minutes later.
25
+ - **Resources 0.5.x created record no needs.** Their teardown starts no shared service until an `up`, a wake or a `restart` of this version records what they need.
26
+
27
+ ### New
28
+
29
+ - **Shared services.** `shared.<name>` in `agentlane.json` declares a server the lanes of one repository use together, with `start`, `stop`, `ready`, `cwd` and `timeoutSeconds` (180 by default). Resources and services name the ones they use in `needs`, and a name not declared under `shared` fails validation. There is one of each per repository, used by the lanes of all its worktrees. agentlane starts it in a new `shared` step of `up`, after the build preconditions and before the resources, when a parked lane wakes, in `restart`, and before a resource teardown that needs it. Two lanes coming up together start it once, and a server whose `ready` already passes is kept without running `start`. It stops 5 minutes after the last lane that needs it parks or ends. The stop runs from the sweep, which runs while any agentlane process runs: each MCP server checks every minute, and every command checks as it starts. With no agentlane process running, a due stop happens at the next agentlane command. A failed stop is tried again a minute later, and a failed start leaves the server counted as running, to stop under the same rule. A stop runs the commands, the folder, the `PATH` and the container tool's variables (`DOCKER_HOST`, `DOCKER_CONTEXT`, `COMPOSE_PROJECT_NAME` and the like) recorded at the last start, and runs in the shared service's log folder once that folder is gone. agentlane never removes a shared service.
30
+ - **`up --no-app`** brings up the project's data alone: the preflight checks that need no device, the preconditions that name no platform, setup, the shared services the resources need, the resources and doctor. It claims no device, browser or port, and builds and starts nothing. Commands run under `exec` with the resources' values. The lane parks and wakes like any other, and a later plain `up` in the folder adds the app to it with the same data. It is refused for a project with no resources, with `--platform`, `--no-cache`, `--refresh-cache` or `--timeout`, and in a folder whose lane already has the app. `restart` in a data-only lane is refused, exit 2, since the lane runs no service.
31
+ - **The guard denies containers that outlive their command.** `docker` and `podman` (and `docker-compose`, `podman-compose`) commands that leave a container running are denied: `run -d` in any of its spellings, `start`, `restart`, `compose up -d`, `--detach` or `--wait`, `compose start`, `compose restart`, `compose run -d`, `podman pod start` and `restart`, and `podman kube play` without `--down`. It reads them through `sh -c`, `npx`, `env`, `sudo`, `nohup`, `setsid`, full paths, split quotes and brace expansion. `run --rm`, foreground `compose up`, `exec`, `stop`, `rm`, `create` and the read-only commands pass, and so do host processes started with `nohup`, `&`, `setsid` or `disown`. The denial names `shared`, `up --no-app` and `exec` as the routes, and `AGENTLANE_ALLOW_CONTAINER=1` as the bypass, which agents use only when the user has asked, in that conversation, for a container outside lanes. agentlane doesn't track or stop such a container. The denial needs no registry, so it works when the state folder can't be read.
32
+ - **`doctor` checks shared services.** A `shared <name>` line for each shared service the lane needs runs its `ready` and fails with `up` as the fix. A data-only lane gets the config, wiring, lane, hook locale, resource and shared lines only.
33
+ - **`status` lists shared services** after the lanes: whether each runs, the lanes that need it, when it stops, and why its last start or stop failed, with its log. `lanes --json` has them in a top-level `shared` array.
34
+
35
+ ### Changed
36
+
37
+ - **`exec` ends with the process that ran it.** When that process exits while the command runs, such as an agent's shell being killed, `exec` sends SIGTERM to the command and every process under it, SIGKILL 5 seconds later to whatever still runs, and exits 129. A command whose caller is gone before it starts never runs. While the caller lives, `exec` reads its parent pid once a second and nothing else changes: the command stays in the terminal's process group, gets Ctrl-C and reads the terminal. `nohup agentlane exec -- <server> &` followed by closing the shell now ends the server too.
38
+ - **`reap` exits 1 when a shared service's stop fails**, as it does on any other problem, and `reap --json` has a `shared` list of the services it stopped.
39
+ - **A teardown starts the shared services its resource needs first.** When that start fails, the teardown doesn't run and its record is kept with `teardown did not run, since shared service <name> did not start`, to be tried again by the next release or reap. One pass tries each failing shared service once.
40
+ - **`restart` starts any shared service the lane needs that isn't running**, before it stops the service, so a failed shared start leaves the running service alone.
41
+ - **The guard hooks start Node for commands that name `docker` or `podman`**, as they do for device and browser tools. `setsid` now passes through like `nohup`, so `setsid <device command>` gets the device check.
42
+ - **`up`'s claim step** reads `claimed lane <id>: no device, browser or port` for a lane that holds none, and a lane with no ports no longer ends the line with a stray comma.
43
+ - **The README, the docs home and the package description now open on the problem agentlane solves**, running several coding agents on one machine.
44
+
45
+ ### Fixed
46
+
47
+ - `agentlane schema` no longer opens the registry, so printing the schema leaves the state folder as it was.
48
+
49
+ ## 0.5.1
50
+
51
+ Three checks no longer fail things that work, and the registry's lock holder names its caller.
52
+
53
+ ### Fixed
54
+
55
+ - **A simulator location nothing reports no longer stops `up`.** locationd reports the simulated location only while an app is receiving one, so on a simulator where no app is, capture hygiene read nothing back after setting the location three times, failed, and `up` stopped before it launched the app. `up` now counts that location as set and says it is unconfirmed: `hygiene: applied location (unconfirmed: nothing read back after setting it 3 times over 46 s; locationd reports a location only while an app is receiving one)`. `doctor` warns instead of failing. A location read back at another coordinate still fails.
56
+ - **`up` keeps a running service whose listener can't be read.** When `lsof` timed out, `up` and `doctor` counted a dev server whose process was alive and whose ready check passed as failed, and `up` stopped and restarted it. Its ready check now stands for it, and `up` says `the listener on <port> could not be read`.
57
+ - **`doctor` sees the Claude Code plugin from a git worktree.** A project-scope install also loads in the git worktrees of the checkout it was installed for, and `doctor` warned there that Claude Code hadn't installed the plugin.
58
+ - **The registry's lock holder names an `exec` and other lane touches.** A busy refusal named a long `exec` as "an unidentified caller"; it now reads, for example, `agentlane exec: sh, on lane ab2ea94d`.
59
+
5
60
  ## 0.5.0
6
61
 
7
62
  A lane now gives its simulator or emulator back when nobody uses it, and ends on its own once its session is gone, whether or not the session ran `release` or its session-end hook fired. The hooks move into every agent's project settings, plugin or not, and `doctor` proves they run. `prune` and the tool installs leave less on disk. This version runs beside 0.4.1 on the same Mac; "Sharing a Mac with 0.4.1" lists what 0.4.1 still does differently.
package/README.md CHANGED
@@ -5,15 +5,37 @@
5
5
  </picture>
6
6
  </p>
7
7
 
8
- <p align="center"><strong>A running copy of your app for every AI coding agent.</strong></p>
9
-
10
8
  <p align="center">
11
9
  <a href="https://www.npmjs.com/package/agentlane"><img src="https://img.shields.io/npm/v/agentlane" alt="npm"></a>
12
- <a href="https://github.com/north-star-hq/agentlane/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT"></a>
10
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT"></a>
13
11
  <a href="https://github.com/north-star-hq/agentlane/actions/workflows/ci.yml"><img src="https://github.com/north-star-hq/agentlane/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
14
12
  </p>
15
13
 
16
- 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.
14
+ <h3 align="center">Stop your coding agents fighting over ports, simulators and databases.</h3>
15
+
16
+ <p align="center">The fast, light way to run a copy of your app for every agent, with tools to see it and drive it, all at the same time.</p>
17
+
18
+ <p align="center"><strong>Reads the screen 50x faster than stock Maestro.</strong></p>
19
+
20
+ <picture>
21
+ <source media="(prefers-color-scheme: dark)" srcset="media/hero-dark.svg">
22
+ <img src="media/hero-light.svg" width="960" alt="Claude Code, Codex and Cursor, each shown with its mark, get their own ports, dev server, database and a browser, iOS simulator or Android emulator from agentlane up. Each types an item into its own copy of the Basket app, ticks items off and takes screenshots, then Codex finishes and its ports and device are released.">
23
+ </picture>
24
+
25
+ Whether you run several Claude Code sessions on one app, Codex and Cursor side by side, or agents testing iOS and Android at once, agentlane keeps them apart.
26
+
27
+ agentlane calls each copy a **lane**. Every lane has:
28
+
29
+ - Its own [ports, dev servers and database](https://north-star-hq.github.io/agentlane/docs/services.html), so no two agents start a server on the same port.
30
+ - Its own [iOS simulator, Android emulator or browser](https://north-star-hq.github.io/agentlane/docs/devices.html), which no other agent can touch.
31
+ - [`look`, `run` and `screenshot`](https://north-star-hq.github.io/agentlane/docs/drive.html), which see and drive the app the same way on all three.
32
+ - [`doctor`](https://north-star-hq.github.io/agentlane/docs/doctor.html), which checks that every server runs this worktree's code before the agent trusts it.
33
+ - [Videos, traces, logs and screenshots](https://north-star-hq.github.io/agentlane/docs/evidence.html) the agent keeps as proof.
34
+ - [Cleanup](https://north-star-hq.github.io/agentlane/docs/guard.html) when the agent is done: servers stop, databases go, and devices go back to the pool.
35
+
36
+ It works with Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and Antigravity, on web apps, iOS and Android. It runs on your machine, with no account.
37
+
38
+ ## Install
17
39
 
18
40
  **1. In your project's root:**
19
41
 
@@ -27,96 +49,74 @@ npx agentlane init
27
49
  Set this project up with agentlane.
28
50
  ```
29
51
 
30
- <sub>`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](https://north-star-hq.github.io/agentlane/docs/getting-started.html) walks through both steps.</sub>
52
+ Once setup reports ready, any agent in the project can take work like this:
31
53
 
32
- <picture>
33
- <source media="(prefers-color-scheme: dark)" srcset="media/hero-dark.svg">
34
- <img src="media/hero-light.svg" width="960" alt="Claude Code, Codex and Cursor, each shown with its mark, get their own lane from agentlane up: ports, dev server, database and a browser, iOS simulator or Android emulator. Each types an item into its own copy of the Basket app, ticks items off and takes screenshots, then Codex finishes and its lane is released.">
35
- </picture>
54
+ > 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.
36
55
 
37
- ## Why agentlane
56
+ ## Speed
38
57
 
39
- - **Every agent, one install.** [Six agents](https://north-star-hq.github.io/agentlane/docs/install.html) get the same CLI, MCP server, skills and hooks from one `init`.
40
- - **Web, iOS and Android in one tool.** [`look`, `run` and `screenshot`](https://north-star-hq.github.io/agentlane/docs/drive.html) work the same on a simulator, an emulator or a browser.
41
- - **The whole environment, per agent.** [Ports, dev servers, a database, sign-in](https://north-star-hq.github.io/agentlane/docs/lanes.html), and a device or browser that no other agent touches.
42
- - **Fast.** A warm lane reads the screen in about 0.15 s. See [Speed](#speed).
43
- - **It checks the app before your agent trusts it.** [`doctor`](https://north-star-hq.github.io/agentlane/docs/doctor.html) confirms that every server runs this worktree's code, and names the fix when one doesn't.
44
- - **Evidence you can open.** [Videos, traces, logs and screenshots](https://north-star-hq.github.io/agentlane/docs/evidence.html), plus the Maestro flows and Playwright tests your agent commits.
45
- - **It cleans up.** When a session ends, [its lane is released](https://north-star-hq.github.io/agentlane/docs/guard.html): services stop, databases are torn down, and devices go back to the pool.
46
- - **Local.** No account, no hosted service, [no telemetry of its own](#security-and-telemetry).
58
+ An agent reads its screen in **0.12 s**, where stock Maestro takes 6.5 s.
47
59
 
48
- ## Speed
60
+ | | With agentlane | Without |
61
+ | ----------------------------- | --------------------------- | ---------------------- |
62
+ | Read the screen | 0.12 s | 6.5 s on stock Maestro |
63
+ | iOS build in a fresh worktree | 6.5 s from the shared cache | 91.5 s |
64
+ | Boot an Android emulator | Under 2 s from Quick Boot | 14.6 s cold |
49
65
 
50
- | On a warm lane, median of 16 calls | iOS simulator | Browser |
51
- | ---------------------------------- | ------------- | ------- |
52
- | Read the screen with `look` | 0.15 s | 0.16 s |
53
- | Take a screenshot | 0.16 s | 0.18 s |
54
- | Click through `playwright-cli` | | 0.81 s |
66
+ [How we measured, and what makes it fast](https://north-star-hq.github.io/agentlane/docs/speed.html)
55
67
 
56
- What makes it fast:
68
+ ## The skills
57
69
 
58
- - **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.
59
- - **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.
60
- - **Quick taps.** On Android, `run --quick` skips Maestro's fixed 750 ms window settle and the screen reads after the tap.
61
- - **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.
62
- - **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.
70
+ [The skills](https://north-star-hq.github.io/agentlane/docs/skills.html) teach an agent the whole loop in your project, from setup to proof.
63
71
 
64
- [Speed](https://north-star-hq.github.io/agentlane/docs/speed.html) on the docs site explains each one.
72
+ - **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.
73
+ - **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.
74
+ - **drive** covers driving the lane's device or browser, turning what worked into a committed flow or test, and keeping evidence.
75
+ - **device** is drive's old name. It sends any run skill that still loads `device` to drive.
76
+ - **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.
77
+ - **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.
65
78
 
66
- <details>
67
- <summary>How these were measured</summary>
79
+ 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.
68
80
 
69
- All on an Apple M4 Max with 48 GB of memory.
81
+ ## agentlane and the tools you already use
70
82
 
71
- - iOS column: `agentlane bench` on the [example app](examples/expo-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.
72
- - 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.
73
- - Port comparison: 16 reads per simulator on another app, stock Maestro 2.8.0 against an early build with the port patch.
74
- - 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.
83
+ agentlane is the same idea as a git worktree, for the running app. A worktree gives each agent its own copy of the code, and a lane gives it its own copy of the app, up and running.
75
84
 
76
- [`bench/README.md`](bench/README.md) has the method, and `agentlane bench` runs it on your machine.
85
+ ### agentlane and Simlock
77
86
 
78
- </details>
87
+ [Simlock](https://github.com/callstackincubator/simlock), from Callstack, leases iOS simulators, Android emulators and enrolled phones to coding agents that run in parallel. An agent asks for a device and gets one back, booted and checked, that no other agent touches until it lets go. A lane holds a simulator, emulator or browser for one agent too, and adds the rest of the running app around it: its ports, dev servers and database.
79
88
 
80
- ## What a lane gives your agent
89
+ ### agentlane and agent-device
81
90
 
82
- **Its own environment**
91
+ [agent-device](https://github.com/callstack/agent-device), also from Callstack, lets coding agents control mobile, TV, desktop and web apps through a CLI, an MCP server and a Node.js API, on more platforms than agentlane covers. It also coordinates device access between agents in parallel worktrees. A lane starts the app's servers and database first, so what the agent drives already runs that worktree's code.
83
92
 
84
- - [Ports](https://north-star-hq.github.io/agentlane/docs/services.html) from a registry on the machine, with your dev servers started on them and checked ready before `up` returns.
85
- - [A database](https://north-star-hq.github.io/agentlane/docs/resources.html), or any resource you declare, created for the lane and torn down when it ends, after a crash too.
86
- - Sign-in through your project's hook, so the app opens signed in.
87
- - A [simulator, emulator](https://north-star-hq.github.io/agentlane/docs/devices.html) or [browser](https://north-star-hq.github.io/agentlane/docs/browsers.html) from a pool. When the pool is full, the request waits for a free device.
88
- - `restart` changes one service's environment, such as a feature flag, without tearing the lane down.
93
+ ### agentlane and portless
89
94
 
90
- **Eyes and hands**
95
+ [portless](https://github.com/vercel-labs/portless), from Vercel Labs, gives each dev server a free port and a stable, named `.localhost` URL, and gives each linked worktree a subdomain of its own. A lane adds the database and the simulator, emulator or browser that go with those servers.
91
96
 
92
- - `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.
93
- - `run` runs Maestro steps and prints what changed.
94
- - In the browser, Playwright's `playwright-cli` (the default) or agent-browser, run through `agentlane exec`.
95
- - [`record save`](https://north-star-hq.github.io/agentlane/docs/drive.html) turns the session's passing steps into a Maestro flow you can commit.
96
- - `device` sets location, permissions, appearance, push notifications, the clipboard and links to open.
97
- - Before launch, `up` sets the device's location, status bar and keyboard, so captures match from run to run.
97
+ ### agentlane and worktrunk
98
98
 
99
- **Evidence and housekeeping**
99
+ [worktrunk](https://github.com/max-sixty/worktrunk) is a CLI for git worktrees, designed for running AI agents in parallel. You switch, list and remove worktrees by branch name, with hooks and shared build caches. A lane runs the app from each worktree, and the same session in a second worktree gets a second lane.
100
100
 
101
- - [`evidence`](https://north-star-hq.github.io/agentlane/docs/evidence.html) keeps videos, Playwright traces, logs and screenshots in a folder that outlives the lane. A failed `run` or `exec` command keeps its own.
102
- - [A hook](https://north-star-hq.github.io/agentlane/docs/guard.html) denies `simctl`, `adb`, `emulator`, `avdmanager`, `playwright-cli` and `agent-browser` commands aimed at another lane's device or browser.
103
- - The next lane taken on the machine cleans up any lane whose session died, and `prune` deletes pool devices no lane holds.
101
+ ### agentlane and Playwright
104
102
 
105
- ## The skills
103
+ [Playwright](https://github.com/microsoft/playwright) drives Chromium, Firefox and WebKit with one API, and its `playwright-cli` is built for coding agents. agentlane drives the browser with it by default. A lane gives each agent its own Chrome for Testing, with a profile no other lane can read, and agentlane's hook stops one agent's commands from reaching another lane's browser.
106
104
 
107
- [The skills](https://north-star-hq.github.io/agentlane/docs/skills.html) 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.
105
+ ### agentlane and Maestro
108
106
 
109
- - **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.
110
- - **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.
111
- - **drive** covers driving the lane's device or browser, turning what worked into a committed flow or test, and keeping evidence.
112
- - **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.
113
- - **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.
107
+ [Maestro](https://github.com/mobile-dev-inc/Maestro) tests Android, iOS and web apps through YAML flows, and its MCP server lets coding agents drive a live device. agentlane drives every simulator and emulator with it and keeps a Maestro session warm between calls. Its patched Maestro gives each iOS simulator's runner a port of its own, so a second simulator doesn't start cold on every call.
114
108
 
115
- 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.
109
+ ### agentlane and Conductor
116
110
 
117
- Once setup reports ready, any agent in the project can take work like this:
111
+ [Conductor](https://www.conductor.build/) runs Claude Code, Codex, Cursor and OpenCode in parallel, each task in its own workspace and branch, on your Mac or in Conductor Cloud's sandboxes. A setup script runs in each new workspace to install dependencies and prepare files, and each workspace gets its own range of ports for the app's servers. On your Mac, a lane adds a database and a simulator, emulator or browser to each workspace.
118
112
 
119
- > 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.
113
+ ### agentlane and Paradev
114
+
115
+ [Paradev](https://github.com/ParadevAI/Paradev), formerly Superset, is an open-source desktop app for running CLI coding agents in parallel. Each task gets its own git worktree, branch and terminals, and a built-in browser previews each workspace's dev server. Setup and teardown scripts run as each workspace is created and deleted, to install its dependencies or to start its containers and remove them. A lane gives each agent an iOS simulator or Android emulator of its own as well.
116
+
117
+ ### agentlane and your agent's own worktrees
118
+
119
+ Claude Code's `--worktree`, the Codex app's worktrees and Cursor's worktrees each give an agent its own checkout, so parallel edits don't collide. Codex and Cursor can also run setup scripts in every new one. A lane runs the app from that checkout, and `doctor` confirms that every server is running that worktree's code.
120
120
 
121
121
  ## Where it runs
122
122
 
@@ -149,18 +149,14 @@ agentlane is built on these projects, and we're grateful to their authors:
149
149
  - [agent-browser](https://github.com/vercel-labs/agent-browser) is the other browser driver a lane can run.
150
150
  - [pstack](https://github.com/cursor/plugins/tree/main/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.
151
151
 
152
- Other projects worth knowing, from people working on the same problem:
153
-
154
- - [agent-device](https://github.com/callstack/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.
155
- - [MobileBuildMCP](https://github.com/getsentry/MobileBuildMCP) by Sentry, formerly XcodeBuildMCP: an MCP server and CLI with tools for agents working on iOS and macOS projects.
156
- - 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.
157
-
158
152
  The Android robot in the animation is Google's, used under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/).
159
153
 
160
154
  ## Documentation
161
155
 
162
156
  The [docs site](https://north-star-hq.github.io/agentlane/) has per-agent setup, the config and CLI reference, platform requirements and troubleshooting, with an `llms.txt` for agents. [`examples/expo-app/`](examples/expo-app/) is the app agentlane is tested on, and [`CHANGELOG.md`](CHANGELOG.md) lists every release.
163
157
 
158
+ Star the repository if agentlane helps you. It helps other people find it.
159
+
164
160
  ## License
165
161
 
166
162
  [MIT](LICENSE). The patched Maestro is Apache-2.0; [`maestro/`](maestro/) holds its patches and notice.
@@ -1,3 +1,4 @@
1
+ import { spawnSync } from 'node:child_process';
1
2
  import fs from 'node:fs';
2
3
  import path from 'node:path';
3
4
  import { FORMER, TOOL } from "../name.js";
@@ -76,10 +77,22 @@ function sameDir(a, b) {
76
77
  return path.resolve(a) === path.resolve(b);
77
78
  }
78
79
  }
80
+ /** The folder itself and, inside a git worktree, the repository's main checkout. */
81
+ function checkoutsOf(root, env) {
82
+ const result = spawnSync('git', ['-C', root, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
83
+ encoding: 'utf8',
84
+ env,
85
+ });
86
+ if (result.status !== 0)
87
+ return [root];
88
+ const common = result.stdout.trim();
89
+ return path.basename(common) === '.git' ? [root, path.dirname(common)] : [root];
90
+ }
79
91
  /**
80
92
  * Where Claude Code loads the enabled plugin from on this Mac. Claude Code records what it installed in
81
93
  * `plugins/installed_plugins.json` under its config folder: format 2 maps `<plugin>@<marketplace>` to a list of
82
- * installs, each with a `scope`, a `projectPath` for project and local scopes, and an `installPath`.
94
+ * installs, each with a `scope`, a `projectPath` for project and local scopes, and an `installPath`. A project-scope
95
+ * install also loads in the git worktrees of the checkout it names (Claude Code 2.1.325).
83
96
  */
84
97
  export function claudePluginInstall(root, env) {
85
98
  const session = sessionPluginDir(env);
@@ -94,6 +107,7 @@ export function claudePluginInstall(root, env) {
94
107
  const plugins = jsonObjectAt(file)?.plugins;
95
108
  if (typeof plugins !== 'object' || plugins === null)
96
109
  return { kind: 'unknown' };
110
+ let checkouts;
97
111
  for (const key of keys) {
98
112
  const listed = plugins[key];
99
113
  const installs = Array.isArray(listed) ? listed : listed === undefined ? [] : [listed];
@@ -101,7 +115,8 @@ export function claudePluginInstall(root, env) {
101
115
  if (typeof install !== 'object' || install === null)
102
116
  continue;
103
117
  const { scope, projectPath, installPath } = install;
104
- const here = scope === undefined || scope === 'user' || sameDir(projectPath, root);
118
+ checkouts ??= checkoutsOf(root, env);
119
+ const here = scope === undefined || scope === 'user' || checkouts.some(dir => sameDir(projectPath, dir));
105
120
  if (here && typeof installPath === 'string')
106
121
  return { kind: 'loaded', dir: installPath };
107
122
  }
@@ -19,6 +19,8 @@ export const GUARDED_WORDS = [
19
19
  'playwright-cli',
20
20
  '@playwright/cli',
21
21
  'agent-browser',
22
+ 'docker',
23
+ 'podman',
22
24
  ];
23
25
  /**
24
26
  * The hook's input arrives as JSON, which writes a backslash as `\\` and a newline as `\n`, and Copilot's `toolArgs` is
@@ -39,7 +41,7 @@ function worktreeFallback() {
39
41
  /**
40
42
  * The command an agent's hook runs: the project's own toolkit, found from the folder the hook runs in upwards, else in
41
43
  * the first worktree of the same repository that has one. The guard starts the toolkit only for a command that names
42
- * a device or browser tool. Without a toolkit it allows and exits 0, because Copilot denies the tool call on any other
44
+ * a device, browser or container tool. Without a toolkit it allows and exits 0, because Copilot denies the tool call on any other
43
45
  * exit and Gemini on exit 2 or more, and Cursor needs a JSON answer.
44
46
  */
45
47
  export function hookCommand(agent, event) {
package/dist/cli.js CHANGED
@@ -35,6 +35,8 @@ Options:
35
35
  --version Print the version.
36
36
  `;
37
37
  const GROUPS = [REGISTRY_HELP, UP_HELP, DRIVER_HELP, HOOK_HELP, AGENT_HELP, BENCH_HELP];
38
+ /** The commands that don't pass by the sweep first: those that run it, those that pass by later, and `schema`, which never opens the state folder. */
39
+ const WITHOUT_PASS_BY = new Set(['hook', SWEEP_COMMAND, 'reap', 'schema']);
38
40
  function commandHelp(command) {
39
41
  for (const group of GROUPS) {
40
42
  const text = helpOf(group, command);
@@ -83,7 +85,7 @@ async function main(args) {
83
85
  const passingBy = () => {
84
86
  passBy({ dir: state }, startSweep);
85
87
  };
86
- if (command !== 'hook' && command !== SWEEP_COMMAND && command !== 'reap')
88
+ if (!WITHOUT_PASS_BY.has(command))
87
89
  passingBy();
88
90
  const mac = process.platform === 'darwin';
89
91
  const android = createEmulatorBackend({ env: process.env, logDir: path.join(state, 'emulators') });
@@ -31,6 +31,7 @@ export const STATUS_BAR_PIN_FIELDS = {
31
31
  'Battery Level': '100',
32
32
  };
33
33
  const LOCATION_FRESH_MS = 3000;
34
+ const LOCATION_UNHEARD = 'locationd reports a location only while an app is receiving one';
34
35
  const LOCATION_HEARD_MS = 300_000;
35
36
  const COORDINATE_TOLERANCE = 5e-8;
36
37
  export class HygieneError extends DeviceStateError {
@@ -62,6 +63,9 @@ function formatStatusBar(fields) {
62
63
  const entries = Object.entries(fields ?? {});
63
64
  return entries.length === 0 ? 'no overrides' : entries.map(([key, value]) => `${key} ${value}`).join(', ');
64
65
  }
66
+ function formatWindow(ms) {
67
+ return ms % 60_000 === 0 ? `${String(ms / 60_000)} min` : `${String(Math.round(ms / 1000))} s`;
68
+ }
65
69
  function message(error) {
66
70
  return error instanceof Error ? error.message : String(error);
67
71
  }
@@ -103,6 +107,7 @@ function steps(tools, udid, options) {
103
107
  }
104
108
  },
105
109
  tries: () => `after setting it ${String(sets)} time${sets === 1 ? '' : 's'} over ${String(Math.round((tools.now().getTime() - locationSetAt.getTime()) / 1000))} s`,
110
+ unheard: LOCATION_UNHEARD,
106
111
  };
107
112
  const keyboardStep = {
108
113
  name: 'keyboard',
@@ -147,10 +152,18 @@ function steps(tools, udid, options) {
147
152
  export async function checkHygiene(tools, udid, options = {}) {
148
153
  await requireBooted(tools, udid);
149
154
  const checks = [];
150
- for (const step of steps(tools, udid, { locationLookbackMs: LOCATION_HEARD_MS, ...options })) {
155
+ const lookbackMs = options.locationLookbackMs ?? LOCATION_HEARD_MS;
156
+ for (const step of steps(tools, udid, { ...options, locationLookbackMs: lookbackMs })) {
151
157
  try {
152
158
  const got = await step.read();
153
- checks.push({ step: step.name, wanted: step.wanted, got: step.format(got), ok: step.matches(got) });
159
+ const unheard = got === undefined ? step.unheard : undefined;
160
+ checks.push({
161
+ step: step.name,
162
+ wanted: step.wanted,
163
+ got: step.format(got),
164
+ ok: step.matches(got) || unheard !== undefined,
165
+ ...(unheard ? { unconfirmed: `nothing read back in the last ${formatWindow(lookbackMs)}; ${unheard}` } : {}),
166
+ });
154
167
  }
155
168
  catch (error) {
156
169
  checks.push({ step: step.name, wanted: step.wanted, got: `unreadable (${message(error)})`, ok: false });
@@ -172,7 +185,9 @@ export async function applyHygiene(tools, udid, options = {}) {
172
185
  }
173
186
  await step.apply();
174
187
  const after = await step.readBack();
175
- const ok = step.matches(after);
188
+ const unheard = after === undefined ? step.unheard : undefined;
189
+ const ok = step.matches(after) || unheard !== undefined;
190
+ const tries = step.tries?.();
176
191
  reports.push({
177
192
  step: step.name,
178
193
  wanted: step.wanted,
@@ -180,7 +195,8 @@ export async function applyHygiene(tools, udid, options = {}) {
180
195
  after: step.format(after),
181
196
  changed: true,
182
197
  ok,
183
- ...(!ok && step.tries ? { tries: step.tries() } : {}),
198
+ ...(!ok && tries ? { tries } : {}),
199
+ ...(unheard ? { unconfirmed: `nothing read back${tries ? ` ${tries}` : ''}; ${unheard}` } : {}),
184
200
  });
185
201
  }
186
202
  catch (error) {
package/dist/hooks/run.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { spawn } from 'node:child_process';
2
2
  import fs from 'node:fs';
3
3
  import path from 'node:path';
4
+ import { killGroup } from "../processes.js";
4
5
  export function describeExit(run) {
5
6
  if (run.timedOut)
6
7
  return `ran past its ${String((run.timeoutMs ?? 0) / 1000)} s and was stopped`;
@@ -28,13 +29,18 @@ export function tail(file, lines = 30) {
28
29
  .map(line => ` | ${line}`)
29
30
  .join('\n');
30
31
  }
31
- function runShell(command, cwd, env, out, timeoutMs) {
32
+ function endGroupOf(child) {
33
+ if (child.pid === undefined || !killGroup(child.pid))
34
+ child.kill('SIGKILL');
35
+ }
36
+ function runShell(command, out, options) {
32
37
  const started = Date.now();
38
+ const { beforeRun, timeoutMs } = options;
33
39
  return new Promise((resolve, reject) => {
34
- const child = spawn('/bin/sh', ['-c', command], {
35
- cwd,
36
- env,
37
- stdio: ['ignore', out, out],
40
+ const child = spawn('/bin/sh', ['-c', beforeRun ? `read -r _ || exit 125\n${command}` : command], {
41
+ cwd: options.cwd,
42
+ env: options.env,
43
+ stdio: [beforeRun ? 'pipe' : 'ignore', out, out],
38
44
  detached: timeoutMs !== undefined,
39
45
  });
40
46
  let timedOut = false;
@@ -42,12 +48,7 @@ function runShell(command, cwd, env, out, timeoutMs) {
42
48
  ? undefined
43
49
  : setTimeout(() => {
44
50
  timedOut = true;
45
- try {
46
- process.kill(-(child.pid ?? 0), 'SIGKILL');
47
- }
48
- catch {
49
- child.kill('SIGKILL');
50
- }
51
+ endGroupOf(child);
51
52
  }, timeoutMs);
52
53
  child.once('error', error => {
53
54
  clearTimeout(timer);
@@ -57,6 +58,19 @@ function runShell(command, cwd, env, out, timeoutMs) {
57
58
  clearTimeout(timer);
58
59
  resolve({ code, signal, ms: Date.now() - started, ...(timedOut ? { timedOut } : {}) });
59
60
  });
61
+ if (!beforeRun || child.pid === undefined)
62
+ return;
63
+ child.stdin?.on('error', () => undefined);
64
+ try {
65
+ beforeRun(child.pid);
66
+ }
67
+ catch (error) {
68
+ clearTimeout(timer);
69
+ endGroupOf(child);
70
+ reject(error instanceof Error ? error : new Error(String(error)));
71
+ return;
72
+ }
73
+ child.stdin?.end('\n');
60
74
  });
61
75
  }
62
76
  export async function runHook(hook, command, options) {
@@ -65,7 +79,7 @@ export async function runHook(hook, command, options) {
65
79
  const fd = fs.openSync(options.log, 'a');
66
80
  let result;
67
81
  try {
68
- result = await runShell(command, options.cwd, options.env, fd, options.timeoutMs);
82
+ result = await runShell(command, fd, options);
69
83
  }
70
84
  finally {
71
85
  fs.closeSync(fd);
@@ -83,12 +97,23 @@ export async function runHook(hook, command, options) {
83
97
  }
84
98
  export function runCheck(command, options) {
85
99
  const started = Date.now();
100
+ const ownGroup = options.ownGroup === true;
86
101
  return new Promise((resolve, reject) => {
87
- const child = spawn('/bin/sh', ['-c', command], { cwd: options.cwd, env: options.env, stdio: ['ignore', 'pipe', 'pipe'] });
102
+ const child = spawn('/bin/sh', ['-c', command], {
103
+ cwd: options.cwd,
104
+ env: options.env,
105
+ stdio: ['ignore', 'pipe', 'pipe'],
106
+ detached: ownGroup,
107
+ });
88
108
  const chunks = [];
89
109
  child.stdout.on('data', (chunk) => chunks.push(chunk));
90
110
  child.stderr.on('data', (chunk) => chunks.push(chunk));
91
- const timer = setTimeout(() => child.kill('SIGKILL'), options.timeoutMs ?? 30_000);
111
+ const timer = setTimeout(() => {
112
+ if (ownGroup)
113
+ endGroupOf(child);
114
+ else
115
+ child.kill('SIGKILL');
116
+ }, options.timeoutMs ?? 30_000);
92
117
  child.once('error', error => {
93
118
  clearTimeout(timer);
94
119
  reject(error);