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/dist/up-cli.js CHANGED
@@ -6,7 +6,7 @@ import { DeviceCommandError } from "./devices/xcrun.js";
6
6
  import { DriverError } from "./driver/errors.js";
7
7
  import { HookFailed } from "./hooks/run.js";
8
8
  import { CLI, CONFIG_FILE, envName, TOOL } from "./name.js";
9
- import { findProjectConfig, forPlatform, loadProjectConfig, ProjectConfigError } from "./project/config.js";
9
+ import { findProjectConfig, forPlatform, loadProjectConfig, ProjectConfigError, withoutApp } from "./project/config.js";
10
10
  import { PROJECT_PLATFORMS, schemaText } from "./project/schema.js";
11
11
  import { shellQuote } from "./registry/format.js";
12
12
  import { ownerKey, resolveOwner } from "./registry/owner.js";
@@ -16,12 +16,13 @@ import { readRegistryStatus } from "./registry/registry.js";
16
16
  import { touchOwnLane } from "./registry/touch.js";
17
17
  import { resolveFolder } from "./registry-cli.js";
18
18
  import { ServiceFailed } from "./services/services.js";
19
- import { laneDir, readUpRecord } from "./up/lane-files.js";
19
+ import { configPlatform, laneDir, readUpRecord } from "./up/lane-files.js";
20
20
  import { diagnose, renderDoctor } from "./up/doctor.js";
21
21
  import { execInLane } from "./up/exec.js";
22
22
  import { Unmet } from "./up/preflight.js";
23
23
  import { ResourceFailed } from "./up/resources.js";
24
24
  import { restart } from "./up/restart.js";
25
+ import { SharedServiceFailed } from "./up/shared.js";
25
26
  import { runSetup } from "./up/setup.js";
26
27
  import { up } from "./up/up.js";
27
28
  import { groupUsage, helpOf } from "./usage.js";
@@ -30,11 +31,17 @@ export const UP_HELP = {
30
31
  title: `Environment (reads ${CONFIG_FILE} from this folder or the ones above it):`,
31
32
  entries: {
32
33
  up: ` up Take this worktree from bare to the running app on its own simulator or emulator,
33
- or to its web app's services: preflight, claim, setup, resources, build (through the
34
- build cache), services, hygiene, launch, signin, doctor; a web app skips the device
35
- steps. Prints shell exports on stdout: eval "$(${TOOL} up)".
34
+ or to its web app's services: preflight, claim, setup, build preconditions, shared
35
+ services, resources, build (through the build cache), services, hygiene, launch,
36
+ signin, doctor; a web app skips the device steps. Prints shell exports on stdout:
37
+ eval "$(${TOOL} up)".
36
38
  --platform <name> ios, android or web (default: the config's app.platform, or
37
39
  web when it declares only a web app)
40
+ --no-app bring up the project's data alone, for commands that need
41
+ only its resources (tests, say): preflight, setup, the shared
42
+ services the resources need, and the resources. No device,
43
+ browser or port, and nothing built or started; run the
44
+ commands under exec. A later up here adds the app
38
45
  --no-setup skip the setup hook (it already ran in this worktree)
39
46
  --no-cache build without the build cache
40
47
  --refresh-cache build, and replace the cached build
@@ -59,10 +66,12 @@ export const UP_HELP = {
59
66
  With a driver block, 'maestro' there is the toolkit's build on this lane's device,
60
67
  with JDK 17 and the lane's runner token: ${TOOL} exec -- maestro test <flow.yaml>
61
68
  Without one, or with an invalid config or no running device, 'maestro' says why and
62
- runs nothing.
69
+ runs nothing. When the process that ran exec exits, exec stops the command and every
70
+ process under it (SIGTERM, then SIGKILL 5 s later) and exits 129.
63
71
  `,
64
72
  doctor: ` doctor Is this worktree's instance worth driving? Checks the lane, toolchain, device,
65
- app, launch, services and hygiene, read-only; exit 1 names each fix.
73
+ app, launch, services and hygiene, read-only; exit 1 names each fix. A lane up --no-app
74
+ made gets the lane, its resources and its shared services checked.
66
75
  --platform <name> check the config for ios, android or web, as up --platform builds it;
67
76
  a lane holding the other platform's device fails the lane check
68
77
  (default: the platform up ran for, else the config's)
@@ -119,6 +128,7 @@ function report(error, command, deps) {
119
128
  }
120
129
  if (error instanceof HookFailed ||
121
130
  error instanceof ResourceFailed ||
131
+ error instanceof SharedServiceFailed ||
122
132
  error instanceof ServiceFailed ||
123
133
  error instanceof DeviceStateError ||
124
134
  error instanceof DeviceBackendError ||
@@ -136,21 +146,34 @@ async function runUp(args, deps, stdout) {
136
146
  args,
137
147
  strict: true,
138
148
  options: {
149
+ 'no-app': { type: 'boolean', default: false },
139
150
  'no-setup': { type: 'boolean', default: false },
140
151
  'no-cache': { type: 'boolean', default: false },
141
152
  'refresh-cache': { type: 'boolean', default: false },
142
- timeout: { type: 'string', default: '600' },
153
+ timeout: { type: 'string' },
143
154
  worktree: { type: 'string' },
144
155
  platform: { type: 'string' },
145
156
  json: { type: 'boolean', default: false },
146
157
  },
147
158
  });
148
159
  const platform = parsePlatform(values.platform);
160
+ if (values['no-app']) {
161
+ const given = [
162
+ ['--platform', platform !== undefined],
163
+ ['--no-cache', values['no-cache']],
164
+ ['--refresh-cache', values['refresh-cache']],
165
+ ['--timeout', values.timeout !== undefined],
166
+ ];
167
+ const clash = given.find(([, on]) => on)?.[0];
168
+ if (clash)
169
+ throw new UsageError(`--no-app and ${clash} are exclusive`, 'pass one of them');
170
+ }
149
171
  const result = await up(deps, {
150
172
  platform,
173
+ app: !values['no-app'],
151
174
  setup: !values['no-setup'],
152
175
  cacheMode: cacheMode(values['no-cache'], values['refresh-cache']),
153
- waitMs: parseSeconds(values.timeout, '--timeout'),
176
+ waitMs: parseSeconds(values.timeout ?? '600', '--timeout'),
154
177
  worktree: values.worktree,
155
178
  });
156
179
  if (values.json) {
@@ -207,8 +230,8 @@ async function runDoctor(args, deps, stdout) {
207
230
  else {
208
231
  try {
209
232
  const loaded = loadProjectConfig(file);
210
- const platform = asked ?? record?.platform ?? lane?.device?.platform;
211
- config = platform === undefined ? loaded : forPlatform(loaded, platform);
233
+ const platform = asked ?? configPlatform(record, lane);
234
+ config = platform === undefined ? loaded : platform === null ? withoutApp(loaded) : forPlatform(loaded, platform);
212
235
  }
213
236
  catch (error) {
214
237
  configProblem = error.message;
package/package.json CHANGED
@@ -1,19 +1,25 @@
1
1
  {
2
2
  "name": "agentlane",
3
- "version": "0.5.0",
4
- "description": "Gives each coding agent its own lane: a running copy of your app with its own ports, dev servers, database, and a simulator, emulator or browser to drive it.",
3
+ "version": "0.6.0",
4
+ "description": "Run several AI coding agents on one machine, each with its own ports, dev servers, database and simulator, emulator or browser. Works with Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and Antigravity, on web, iOS and Android.",
5
5
  "keywords": [
6
6
  "ai-agents",
7
7
  "coding-agents",
8
+ "parallel-agents",
8
9
  "mcp",
9
10
  "claude-code",
10
11
  "codex",
11
12
  "cursor",
13
+ "github-copilot",
14
+ "gemini-cli",
15
+ "antigravity",
12
16
  "ios-simulator",
13
17
  "android-emulator",
14
18
  "playwright",
15
19
  "maestro",
16
20
  "worktrees",
21
+ "dev-server",
22
+ "port-conflicts",
17
23
  "dev-environment"
18
24
  ],
19
25
  "homepage": "https://north-star-hq.github.io/agentlane/",
@@ -35,6 +35,16 @@
35
35
  "$ref": "#/$defs/resource"
36
36
  }
37
37
  },
38
+ "shared": {
39
+ "type": "object",
40
+ "description": "The servers the lanes of this repository use together, such as the database server each lane's database lives in, by name. There is one of each per repository, used by the lanes of all its worktrees. A lane needs a shared service when one of its resources or services names it in `needs`. agentlane starts a shared service when a lane needs it, and stops it 5 minutes after the last lane that needs it parks or ends; it never removes one. A shared service whose start failed may be partly up, so it counts as running and stops under the same rule. A stop runs the commands, with the PATH and the variables that choose a container tool's daemon and project, as they were at the shared service's last start, so a change to them counts from its next start.",
41
+ "propertyNames": {
42
+ "pattern": "^[a-z][a-z0-9-]*$"
43
+ },
44
+ "additionalProperties": {
45
+ "$ref": "#/$defs/shared"
46
+ }
47
+ },
38
48
  "hooks": {
39
49
  "$ref": "#/$defs/hooks"
40
50
  },
@@ -398,6 +408,52 @@
398
408
  "exclusiveMinimum": 0,
399
409
  "default": 120,
400
410
  "description": "How long teardown may run before it is stopped and counted as failed."
411
+ },
412
+ "needs": {
413
+ "type": "array",
414
+ "items": {
415
+ "type": "string",
416
+ "pattern": "^[a-z][a-z0-9-]*$"
417
+ },
418
+ "uniqueItems": true,
419
+ "description": "The shared services this uses, by their names under `shared`."
420
+ }
421
+ }
422
+ },
423
+ "shared": {
424
+ "type": "object",
425
+ "additionalProperties": false,
426
+ "required": [
427
+ "start",
428
+ "stop",
429
+ "ready"
430
+ ],
431
+ "properties": {
432
+ "start": {
433
+ "type": "string",
434
+ "minLength": 1,
435
+ "description": "A shell command that starts the server and exits, leaving it running. It must cope with running twice and with finding the server already running."
436
+ },
437
+ "stop": {
438
+ "type": "string",
439
+ "minLength": 1,
440
+ "description": "A shell command that stops the server and keeps its data. It must cope with running twice and with finding the server already stopped, or only partly started."
441
+ },
442
+ "ready": {
443
+ "type": "string",
444
+ "minLength": 1,
445
+ "description": "A shell command that exits 0 when the server answers. agentlane also runs it to tell whether the shared service is running."
446
+ },
447
+ "cwd": {
448
+ "type": "string",
449
+ "minLength": 1,
450
+ "description": "The directory start, stop and ready run in, relative to this file."
451
+ },
452
+ "timeoutSeconds": {
453
+ "type": "number",
454
+ "exclusiveMinimum": 0,
455
+ "default": 180,
456
+ "description": "How long start may run, and then how long ready may take to pass, before the start counts as failed; and how long stop may run before it counts as failed."
401
457
  }
402
458
  }
403
459
  },
@@ -492,6 +548,15 @@
492
548
  "description": "The argument's value; {port} is the service's port."
493
549
  }
494
550
  }
551
+ },
552
+ "needs": {
553
+ "type": "array",
554
+ "items": {
555
+ "type": "string",
556
+ "pattern": "^[a-z][a-z0-9-]*$"
557
+ },
558
+ "uniqueItems": true,
559
+ "description": "The shared services this uses, by their names under `shared`."
495
560
  }
496
561
  }
497
562
  },
@@ -13,7 +13,7 @@ The output is the project's `agentlane.json`, its committed flows and tests adap
13
13
 
14
14
  Done when step 5 has passed: the run skill's own instructions, followed from a fresh lane, brought each app up to `doctor` ready, drove one mapped feature per app, and left evidence that still exists after `release`.
15
15
 
16
- When the `setup` skill sent you here, its survey answers step 1 and its decisions (which apps, data per lane or shared, how sign-in gets a session) settle what step 2 writes; take them as given and do the rest.
16
+ When the `setup` skill sent you here, its survey answers step 1 and its decisions (which apps, which data each lane gets and the server it lives in, how sign-in gets a session) settle what step 2 writes; take them as given and do the rest.
17
17
 
18
18
  ## 1. Interview the repo, not the user
19
19
 
@@ -23,7 +23,7 @@ Answer these from the codebase, and ask the user only what you can't observe:
23
23
  - **Run:** how does each app start locally? Prefer the repo's own scripts. Note the long-running servers (Metro, an API, a web dev server, workers), the ports they bind by default, devices, env files, seed data and auth.
24
24
  - **Drive:** what can act on it programmatically? For a mobile app, the device tools (load the `drive` skill) on the claimed simulator, plus the project's committed Maestro flows. For a web app, the lane's browser through its driver, plus the project's Playwright suites. Otherwise existing harnesses first (curl-able endpoints, a debug port), then a generic recipe: a PTY for a CLI, HTTP for a service.
25
25
  - **Observe:** what evidence can be captured: screenshots, recordings, traces, logs, response bodies, exit codes, database state.
26
- - **Data:** where the app's data lives, and how the project's tests create and reset it today (migrations, a seed script, a Docker database, a SQLite file, fixtures). That decides whether each lane gets its own copy (a resource, step 2) or shares one.
26
+ - **Data:** where the app's data lives, the server it lives in and what starts that server today, and how the project's tests create and reset it (migrations, a seed script, a Docker database, a SQLite file, fixtures), test-only databases included. That decides what each lane gets its own copy of (a resource, step 2) and which server the lanes share.
27
27
  - **Sign-in:** how a user signs in, which test accounts exist and where their credentials come from, and whether the project already has a seam (a token endpoint, a deep link, a Playwright setup project that saves a login).
28
28
  - **Isolate:** can two instances run side by side? Every port the app or its servers hard-code is a collision between agents. The toolkit claims a port per service and passes it in, so each server has to take its port from the environment, and the mobile app has to take its API address at launch (a launch argument in debug builds) instead of a baked-in one. Shared outside state, such as a hosted dev database or test accounts, stays shared: say so in the skill and name what must be cleaned up after a write.
29
29
  - **Worktrees:** agents work in git worktrees, often inside the repo (Claude Code puts them under `.claude/worktrees/`). Check that the project's watchers and test runners (Metro, Jest's haste map, Vite, linters, Playwright's test match) don't scan them, and add excludes where they do.
@@ -37,7 +37,8 @@ When a run skill already exists, read it and its scripts first. Keep what works
37
37
  - **Apps:** `app` for the mobile app, `web` for the web app (`service`, the service that serves it, and `path`, the page to open), or both. `web.browser.driver` picks the browser driver: `playwright` (the default) or `agent-browser` when the project already uses it. `web.browser.headed: true` shows the window for a person to watch, with Playwright only; agent-browser runs headless.
38
38
  - **Device:** when committed flows tap by point, or the repo says which device they were measured on, pin that model in `app.device` with `strict: true` (`{"type": "iPhone 17", "strict": true}`, or under `app.ios` or `app.android` when only one platform's flows depend on it). Without `strict`, a full pool hands the lane another model, and the points land elsewhere on its screen.
39
39
  - **Services:** each long-running server with its start command, reading its port from `AGENTLANE_<SERVICE>_PORT`, and a readiness check. `platforms` limits a service to the apps that need it, so a web `up` doesn't start Metro. When a server's CLI sends usage telemetry, switch it off in the start command with the variable the CLI documents (`EXPO_NO_TELEMETRY=1`, `NEXT_TELEMETRY_DISABLED=1`), since every lane starts its own copy of the server.
40
- - **Resources,** for data each lane gets its own copy of: `create`, `exports` and `teardown`. `create` runs once per lane, after setup and before the services, and appends a `NAME=value` line for each declared export to the file at `$AGENTLANE_EXPORTS` (`echo "DATABASE_URL=$url" >> "$AGENTLANE_EXPORTS"`); anything it prints only goes to the log. The values then reach every service, hook and `exec`, and replace whatever the caller's shell had. Name the copy after `$AGENTLANE_LANE` so two lanes never meet. `teardown` runs when the lane ends, also after a crash and possibly after the worktree is deleted, so it needs only the exported values (`dropdb … "$DB_NAME"`, `rm -f -- "${DATABASE_PATH:?}"`), never a script from the worktree. Since create runs once per lane, run migrations where every `up` reaches them too, such as in the API's start command.
40
+ - **Shared services,** for the server the lanes' databases live in, such as a Postgres container or a local Supabase stack: one entry under `shared`, used by the lanes of every worktree, with `start`, `stop` and `ready`. agentlane starts it when a lane needs it and stops it 5 minutes after the last lane that needs it parks or ends. `start` starts the server and exits, creating it when it doesn't exist; `stop` stops it and keeps its data (`docker stop`, never `docker rm`); each copes with running twice and with finding the server already in the state it sets; `ready` exits 0 when the server answers. The stop may run after the worktree that started it is gone, so write all three inline, with no script from the worktree, and give the container no restart policy (`--restart unless-stopped` brings it back with no lane). Whatever starts the server today (a recipe a precondition runs, a `docker run` inside a resource's create) moves into `start`. Every resource and service that uses the server names it in `needs`.
41
+ - **Resources,** for data each lane gets its own copy of: `create`, `exports` and `teardown`. `create` runs once per lane, after setup and before the services, and appends a `NAME=value` line for each declared export to the file at `$AGENTLANE_EXPORTS` (`echo "DATABASE_URL=$url" >> "$AGENTLANE_EXPORTS"`); anything it prints only goes to the log. The values then reach every service, hook and `exec`, and replace whatever the caller's shell had. Name the copy after `$AGENTLANE_LANE` so two lanes never meet. `teardown` runs when the lane ends, also after a crash and possibly after the worktree is deleted, so it needs only the exported values (`dropdb … "$DB_NAME"`, `rm -f -- "${DATABASE_PATH:?}"`), never a script from the worktree. Since create runs once per lane, run migrations where every `up` reaches them too, such as in the API's start command. Every database the project's tests create is a resource too, a test-only one included (a resource of its own that exports `TEST_DATABASE_URL`, say), and names its server in `needs`. A create makes the database in the server and never starts the server.
41
42
  - **Hooks** the project owns: `setup`, `build`, `launch` when the built-in launch modes don't fit, `signin`, `teardown`. Hooks are shell commands that read the lane from the environment (`AGENTLANE_DEVICE`, `AGENTLANE_<SERVICE>_PORT`, `AGENTLANE_WEB_URL`, the resources' values); they are non-interactive and fail with a non-zero exit when they didn't do their job.
42
43
  - **Sign-in:** on a device, `signin` signs the launched app in through the project's seam. On the web, `signin` writes the lane's saved login to the file at `$AGENTLANE_STORAGE_STATE`, in Playwright's storage-state format (`{"cookies": [...], "origins": [...]}`), for the web app's origin; the lane's browser starts with it, and the project's tests can load it. Get the session the way a real client does, through the app's own sign-in endpoint with a test account, and write the cookie or token it returns. In a project with both apps, one `signin` hook branches on `$AGENTLANE_PLATFORM`. `up` checks the file and keeps its values out of every log.
43
44
  - **First-run sheets:** a lane's simulator or emulator may never have run the app, so `up` can meet the app's first launch: onboarding, a what's-new sheet, a permission prompt, a rating or cookie banner. Each covers the screen an agent came to capture and takes its taps. On a simulator, `up`'s capture hygiene already marks the keyboard's slide-to-type intro as shown; the app's own sheets are the project's to clear, before anything is captured. Clear each through the app's own seam where there is one, the default or launch argument its debug build reads to mark the sheet seen, set from the `signin` or `launch` hook. A permission prompt stays away once `node_modules/.bin/agentlane device permission grant <service> <bundle id>` has granted the permission before the app asks. Dismiss any other sheet in the sign-in flow with an `optional` tap on its id or label. The run skill names each sheet and how it's cleared, and the feature map's baseline is the screen the app shows once they're gone.
@@ -48,6 +49,8 @@ When a run skill already exists, read it and its scripts first. Keep what works
48
49
  - one per env file a hook or the app needs, and, when the repo documents a failure that stays silent without a particular variable (an app that accepts a sign-in link and stays signed out without its seam key, say), one that the variable has a value, not just that the file exists: `grep -q '^SEAM_KEY=.' .env.test`. The check prints nothing, so the value stays out of every log;
49
50
  - any other state the repo warns about, such as a dirty native project.
50
51
 
52
+ A precondition checks state and never starts a server: that the Docker daemon answers is a precondition, and the container goes under `shared`.
53
+
51
54
  ## 3. Adapt the flows and tests, then write the run skill
52
55
 
53
56
  The project's committed flows and tests are its proof, and they keep passing where they ran before (CI, a person's machine). Adapt them to run in a lane as well; don't replace them.
@@ -63,6 +66,8 @@ The project's committed flows and tests are its proof, and they keep passing whe
63
66
 
64
67
  `.agents/skills/run/SKILL.md` needs frontmatter (`name: run`, and a description naming the app, its surfaces and when to reach for it) and the sections `dev-loop` lists, for each app, each grounded in what the interview found, with no placeholders left. Write every toolkit command in it as `node_modules/.bin/agentlane …`, run from the project root: Codex, Cursor, Copilot and Gemini run the skill's commands in a plain shell, where a bare `agentlane` isn't found, and only Claude Code with the toolkit's plugin has one on the PATH. Any helper ships as an executable script whose invocation the skill shows; a helper the reader has to reverse-engineer is not a helper.
65
68
 
69
+ In the run skill, work that needs the project's data and no app, such as its unit and integration tests, goes through a data-only lane: `node_modules/.bin/agentlane up --no-app`, then `node_modules/.bin/agentlane exec -- <test command>`. The lane starts the shared server and creates the resources, and `exec` hands the tests their values, so no agent starts a database of its own.
70
+
66
71
  When agents keep writing throwaway scripts to click through the app, add a command to the project's CLI instead: a few composable commands that each do real work, `--dry-run` on anything destructive, errors that say what to do, and machine-readable output.
67
72
 
68
73
  ## 4. Seed the feature map
@@ -81,7 +86,7 @@ Leave implementation details out. Name user paths, stable handles, required stat
81
86
 
82
87
  ## 5. Prove it before handing it over
83
88
 
84
- Run the skill's own instructions once, end to end, for each app: `up` (with `--platform` for each), `doctor`, drive one mapped feature, run its committed flow or test under `exec`, capture evidence, `release`. Then confirm the evidence still exists where the skill says it lands; a cleanup that eats the proof fails this step. Read the output of the flows the hooks run during `up` as well (`up` prints each hook's log path): a WARNED step there fails this step until it is fixed. Release after every failed attempt too, so broken tries don't strand processes, ports, devices, browsers or databases. A run skill that was never executed is a draft.
89
+ Run the skill's own instructions once, end to end, for each app: `up` (with `--platform` for each), `doctor`, drive one mapped feature, run its committed flow or test under `exec`, capture evidence, `release`. When the run skill has a data-only route for the tests, run that once too: `up --no-app`, the suite under `exec`, `release`. Then confirm the evidence still exists where the skill says it lands; a cleanup that eats the proof fails this step. Read the output of the flows the hooks run during `up` as well (`up` prints each hook's log path): a WARNED step there fails this step until it is fixed. Release after every failed attempt too, so broken tries don't strand processes, ports, devices, browsers or databases. A run skill that was never executed is a draft.
85
90
 
86
91
  ## 6. Hand over
87
92
 
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: dev-loop
3
- description: The contract for running a project's app as an agent with the toolkit - one lane per session and folder (a simulator or emulator, a browser, the ports for Metro, the API and the web app, and per-lane resources such as a database), `agentlane up` from bare worktree to running app, `doctor` before trusting an instance, `keep` while the user looks at the running app, `release` when done - plus what a project's run skill holds and what counts as proof and evidence from a running app. Use when about to run, build, launch or capture a project's mobile or web app, start its dev servers, hand an agent work that runs the app, or when an agent loses turns to ports, simulators, browsers, databases or half-started servers.
4
- when_to_use: Booting a simulator or emulator, opening the web app in a browser, starting Metro or a dev server, running the app for verification, capture, e2e or debugging; leaving the running app for the user to look at; dispatching agents that will run the app; a project with no agentlane.json or no run skill. Not for test-only work that never runs the app.
3
+ description: The contract for running a project's app as an agent with the toolkit - one lane per session and folder (a simulator or emulator, a browser, the ports for Metro, the API and the web app, and per-lane resources such as a database), `agentlane up` from bare worktree to running app, `up --no-app` for a lane with only the project's data, `doctor` before trusting an instance, `keep` while the user looks at the running app, `release` when done - plus what a project's run skill holds and what counts as proof and evidence from a running app. Use when about to run, build, launch or capture a project's mobile or web app, start its dev servers or its database, run tests that need its data, hand an agent work that runs the app, or when an agent loses turns to ports, simulators, browsers, databases or half-started servers.
4
+ when_to_use: Booting a simulator or emulator, opening the web app in a browser, starting Metro or a dev server, running the app for verification, capture, e2e or debugging; leaving the running app for the user to look at; dispatching agents that will run the app; running tests that need the project's database or another server; a project with no agentlane.json or no run skill. Not for work that needs neither the app nor the project's data.
5
5
  license: Parts adapted from cursor/plugins (pstack) under the MIT License, Copyright (c) 2026 Lauren Tan; the full notice is in LICENSE beside this skill in the toolkit package
6
6
  ---
7
7
 
@@ -15,7 +15,7 @@ The loop is done when you have run `release` in your folder, or held the lane wi
15
15
 
16
16
  ## The loop
17
17
 
18
- 1. **`node_modules/.bin/agentlane up`** takes the folder you're in from bare to the running app. It checks the toolchain and the project's preconditions before claiming anything, claims what the platform needs and ports, runs the project's setup, creates the lane's resources the first time (a database, say, whose values such as `DATABASE_URL` reach every service, hook and `exec`), starts each service on its claimed port and waits until it answers, then runs `doctor`.
18
+ 1. **`node_modules/.bin/agentlane up`** takes the folder you're in from bare to the running app. It checks the toolchain and the project's preconditions before claiming anything, claims what the platform needs and ports, runs the project's setup, starts the shared services the lane needs (the server its database lives in, say), creates the lane's resources the first time (a database, say, whose values such as `DATABASE_URL` reach every service, hook and `exec`), starts each service on its claimed port and waits until it answers, then runs `doctor`.
19
19
  - For the mobile app (`--platform ios`, the default when the project has one, or `--platform android` for an emulator) it also builds through the build cache, applies capture hygiene, and launches and signs in. When another worktree is already building the same cache key, `up` prints "waiting for <worktree>'s build of <key>" and installs that build when it lands (it builds itself after 45 minutes, or at once if that builder has died), so a quiet `up` there is waiting, not stuck.
20
20
  - For the web app (`--platform web`, the default when the project has only a web app) it claims a browser with its own profile, opens the web app in it, signs in through the project's `signin` hook, and prints `the web app is at <url>`. There is no build, and it is ready in seconds.
21
21
  - One lane can hold a device and a browser at once: `up` for one platform keeps what an earlier `up` for the other gave the lane.
@@ -32,6 +32,12 @@ When you hand the running app to the user to look at, hold the lane before you e
32
32
 
33
33
  `node_modules/.bin/agentlane prune` lists what takes disk and nothing uses, each with its size: the pool simulators and emulators no lane holds, shut-down devices named like pool devices that no registry records, and what agentlane 0.2.x left. `prune --yes` deletes it. Every project on the machine shares that pool, and the next lane after a prune waits while a new device is created, so run it when the user asks for disk space back; cleaning up after your own work is `release`.
34
34
 
35
+ ## Work that needs only the data
36
+
37
+ When the work needs the project's data and no running app, such as a test suite that reads its database, run `node_modules/.bin/agentlane up --no-app`, then the work under `node_modules/.bin/agentlane exec -- <command>`. `up --no-app` starts the shared services the resources need and creates the lane's resources, and claims no device, browser or port; `exec` gives the command the resources' values, such as `DATABASE_URL`. The lane parks and wakes like any other, `release` drops its data, and a later plain `up` in the folder adds the app to the same lane.
38
+
39
+ The servers and data a lane uses come from `agentlane.json`, not from containers you start: a `docker run -d` or `docker compose up -d` keeps running after you with nothing to stop it, and the toolkit's guard denies it. When the config lacks the server or the database the work needs, add them, the server under `shared` and the database as a resource (the `setup` skill has the rules), or tell the user what is missing. `AGENTLANE_ALLOW_CONTAINER=1` in front of the command lets a container through; use it only when the user has asked, in this conversation, for a container outside lanes, and tell them agentlane won't track or stop it.
40
+
35
41
  ## Lanes are per session and folder
36
42
 
37
43
  A lane belongs to the session that made it and the folder it was made in. Subagents of one session share the session, so each one works in its own worktree and claims there; that keeps their devices, browsers, ports and databases apart. Release only your own folder's lane. A refusal names the holder and the exact command that recovers: when it's another session's lane, leave it, take your own, or ask; `release --lane <id> --force` is only for a holder you know is finished. Never reach another lane's device, browser or port by hand: `simctl`, `adb` and the browser drivers aimed at what you don't hold are denied by the toolkit's hook.
@@ -20,7 +20,7 @@ Read the repo before deciding anything; the answers are usually there. For each
20
20
 
21
21
  - **Apps:** a mobile app (Expo or React Native, an Xcode project, a Gradle project), a web app (Next.js, Vite, Remix and the like, an admin panel), or both, and where each lives in a monorepo.
22
22
  - **Servers:** every long-running process the apps need (Metro, an API, a web dev server, workers, a local database container), how the repo starts each (package scripts, a justfile or Makefile, Procfile, docker compose, dev scripts), and the port each binds. A hard-coded port is a collision between agents.
23
- - **Data:** the database and other stateful stores, whether they run locally or are hosted, and how the project's tests create, migrate, seed and reset them.
23
+ - **Data:** the database and other stateful stores, whether they run locally or are hosted, the server they live in and how the repo starts it (a compose file, a `just` recipe, a script a precondition or a create calls), and how the project's tests create, migrate, seed and reset them, test-only databases included.
24
24
  - **Sign-in:** how a user signs in, the test accounts, where their credentials come from (variable names in env example files and CI; never print a secret's value), and any seam the tests already use (a token endpoint, a deep link, a Playwright setup project that saves a login).
25
25
  - **Proof that exists:** committed Maestro flows, Playwright suites (and the `@playwright/test` version they pin), other end-to-end tests, and how CI runs them.
26
26
  - **How agents run it today:** run skills (`.agents/skills/run/`, `.claude/skills/run/`), `AGENTS.md`, `CLAUDE.md`, README and docs pages on running locally, and the agent folders the repo commits (`.claude/`, `.codex/`, `.cursor/`, `.gemini/`, `.github/hooks/`, `.agents/`).
@@ -37,7 +37,7 @@ Find out which committed flows and suites pass before you change anything, so yo
37
37
  Decide each of these from the survey, with a one-line reason you'll repeat in the summary:
38
38
 
39
39
  - **Platforms:** declare each app the project ships: `app` for the mobile app, `web` for the web app, or both. A project with an admin panel beside its site has two web services; declare the one agents most need as `web` and the other as a service the run skill opens by URL.
40
- - **Data per lane or shared:** when the tests already create a local database (a Docker Postgres, SQLite, a local Supabase stack), give each lane its own copy as a resource: a database named after the lane, created, migrated and seeded the way the tests do, and dropped at teardown. When the project relies on a shared hosted database with no local equivalent, keep it shared, and have the run skill name what a write must clean up. When both are possible but they differ in a way the user cares about (local needs Docker, lacks an extension, or misses data only the hosted copy has), that is a trade-off to ask about.
40
+ - **Data per lane, and the server it lives in:** when the tests already create a local database (a Docker Postgres, SQLite, a local Supabase stack), give each lane its own copy as a resource: a database named after the lane, created, migrated and seeded the way the tests do, and dropped at teardown. Every database the project's tests create becomes a resource, a test-only one included, such as a test database whose URL a resource of its own exports (`TEST_DATABASE_URL`), so the tests run in a lane rather than against a database someone started by hand. The server those databases live in (the Postgres container, the Supabase stack) is declared under `shared`, and every resource and service that uses it names it in `needs`. agentlane then starts it when a lane needs it and stops it, keeping its data, once no lane does; a server started anywhere else keeps running, and keeps Docker's VM up, after every lane is gone. A precondition checks state, such as that the Docker daemon answers, and never starts a server. When the project relies on a hosted database with no local equivalent, every lane uses that one, and the run skill names what a write must clean up. When both are possible but they differ in a way the user cares about (local needs Docker, lacks an extension, or misses data only the hosted copy has), that is a trade-off to ask about.
41
41
  - **Sign-in:** which account each lane signs in as, and through which seam. Prefer the app's own sign-in endpoint with a test account, called from the `signin` hook; on the web the hook writes the saved login the lane's browser starts with.
42
42
  - **Browser driver:** Playwright, unless the project already drives browsers with agent-browser. When a person wants to watch the browser, Playwright with `web.browser.headed: true`, since agent-browser runs headless only. The project's `@playwright/test` must be the toolkit's Playwright version (`node_modules/.bin/agentlane browser status` names it), or its tests find no browser in a lane; moving the pin to that version is a change setup makes and reports, and a pin the project must keep for another reason is a question for the user.
43
43
  - **Agents to wire:** the agent you are running in, and every agent whose folder the repo already commits. Wherever Claude Code loads the toolkit's plugin (the project's settings, the user's, or the session you run in), `init` leaves Claude Code's skills and MCP server to the plugin rather than writing a second copy, and says which it found; it writes the hooks into `.claude/settings.json` either way, so they run where the plugin isn't installed. When only the user's settings or the session load the plugin, someone who opens the project without it gets no Claude Code skills or MCP server from the committed files; that goes in the summary with init's note.
@@ -52,7 +52,7 @@ Run `node_modules/.bin/agentlane init --agents <list>` (the names it takes: `cla
52
52
 
53
53
  ## 5. Write the config, the run skill and the flows
54
54
 
55
- Load the `create-verification-skill` skill and follow it: your survey and decisions answer its interview, and it writes `agentlane.json` (services, apps, resources, sign-in, preconditions), adapts the committed Maestro flows and Playwright suites to run in a lane while keeping them passing where they ran before, and writes or extends the run skill in `.agents/skills/run/` with its feature map. Keep what a project's existing run skill and dev scripts already get right, and make the servers the project starts by hand into services rather than leaving steps for the agent to repeat.
55
+ Load the `create-verification-skill` skill and follow it: your survey and decisions answer its interview, and it writes `agentlane.json` (services, apps, resources, sign-in, preconditions), adapts the committed Maestro flows and Playwright suites to run in a lane while keeping them passing where they ran before, and writes or extends the run skill in `.agents/skills/run/` with its feature map. Keep what a project's existing run skill and dev scripts already get right, and make the servers the project starts by hand into services, and the server its databases live in into a shared service, rather than leaving steps for the agent to repeat.
56
56
 
57
57
  Once the run skill exists, run `node_modules/.bin/agentlane init --agents <list>` again, so Claude Code's `.claude/skills/` mirrors it too. This step is done when `node_modules/.bin/agentlane doctor`'s `config` line is `ok` (it validates against the schema `node_modules/.bin/agentlane schema` prints), `init --check` exits 0, and create-verification-skill's own completion criterion holds.
58
58