Guide · Lanes 0.0.9

Your first lanes.

Name: Lanes
Author: Autter

Install Lanes, run it once, and your agents put their work in lanes on their own. It takes about five minutes, and every command below is written for your system.

Steps for

Pick your system to see only its commands.

Install Lanes.
One command installs lane and its laned daemon. Every way of installing gets you the same two programs.
Terminal (zsh)any folder
bash or zshany folder
PowerShellany folder
macOS
brew install autter-dev/tap/lanes
macOS
No Homebrew? curl -fsSL https://lanes.autter.dev/install.sh | sh puts Lanes in ~/.local/bin instead.
Linux
curl -fsSL https://lanes.autter.dev/install.sh | sh
Linux
It puts Lanes in ~/.local/bin, on x64 or arm64. If that folder isn't on your PATH yet, the installer prints the line to add. Homebrew on Linux works too: brew install autter-dev/tap/lanes.
Windows
irm https://lanes.autter.dev/install.ps1 | iex
Windows
Run it in PowerShell. It puts lane.exe and laned.exe in %LOCALAPPDATA%\Programs\Lanes\bin and adds that to your PATH, so open a new terminal afterwards. Builds aren't code-signed yet, so Smart App Control on Windows 11 may block them: here's what to do.
lane --version
```
lane 0.0.9 (by Autter)
```
Scoop, npm and plain archives are on the download page.
Set it up once.
Run lane on its own. The first time, it checks Git, your disk and your agents, and puts the agents it finds in lanes: Claude Code, Codex, Cursor, Gemini CLI and GitHub Copilot get Lanes' hooks and a lanes skill in their own user settings. From then on, every repo gets lanes, with nothing more to set up. Nothing is sent while you look around.
Terminal (zsh)any folder
bash or zshany folder
PowerShellany folder
lane
macOS
Every Mac disk is APFS, so a lane is a copy-on-write clone: it shares your files' data instead of copying it.
Linux
On Btrfs or XFS, a lane is a copy-on-write clone. On ext4 it's a plain copy, which works but takes longer and uses more space; lane setup says which one you have.
Windows
On a Dev Drive, a lane is a copy-on-write clone, though every file still costs the drive a few KB, so folders of many small files, like node_modules, save less. On a regular NTFS drive it's a plain copy, which works but takes longer and uses more space. Keep your repos on a Dev Drive if you have one; lane setup shows how to make one, and the git clone command to move a repo there.
Or without the welcome, for a script or a new machine
lane setup --yes
macOS
```
Saved: install count on. Settings are in /Users/you/.config/lane/config.toml.
Agents in lanes:
  Claude Code    set up: its worktrees become lanes, in every repo
  Codex          set up: its worktrees become lanes, in every repo
                 Codex runs new hooks only once you trust them: open /hooks in Codex and trust Lanes' two hooks.
  Cursor         set up: its worktrees become lanes, in every repo
  Gemini CLI     set up: its worktrees become lanes, in every repo
  GitHub Copilot set up: its worktrees become lanes, in every repo
```
Linux
```
Saved: install count on. Settings are in /home/you/.config/lane/config.toml.
Agents in lanes:
  Claude Code    set up: its worktrees become lanes, in every repo
  Codex          set up: its worktrees become lanes, in every repo
                 Codex runs new hooks only once you trust them: open /hooks in Codex and trust Lanes' two hooks.
  Cursor         set up: its worktrees become lanes, in every repo
  Gemini CLI     set up: its worktrees become lanes, in every repo
  GitHub Copilot set up: its worktrees become lanes, in every repo
```
Windows
```
Saved: install count on. Settings are in C:\Users\you\.lane\config.toml.
Agents in lanes:
  Claude Code    set up: its worktrees become lanes, in every repo
  Codex          set up: its worktrees become lanes, in every repo
                 Codex runs new hooks only once you trust them: open /hooks in Codex and trust Lanes' two hooks.
  Cursor         set up: its worktrees become lanes, in every repo
  Gemini CLI     set up: its worktrees become lanes, in every repo
  GitHub Copilot set up: its worktrees become lanes, in every repo
```
Set up Lanes before 0.0.5? Run lane setup once more; the home screen says when an agent isn't in lanes yet. Changed your mind? lane setup --yes --agents off takes back exactly what was added, and nothing else in those files changes.
Once you've chosen, Lanes sends an anonymous install count: a random install id, the version, your OS and CPU type, and how you installed it, once now and once after each upgrade. Nothing else. lane telemetry shows exactly what your machine sends, and lane telemetry off stops it.
Let your agents make lanes.
Start your agents the way you always do. Each task gets a lane of its own: a ready-to-run copy of the repo with its own ports, dependencies and .env. You don't run anything, and agents never edit the same files or fight over a port.
Terminal (zsh)~/code/your-app
bash or zsh~/code/your-app
PowerShellC:\code\your-app
Claude Code
claude -w fix-auth
Or just ask Claude for the work: the lanes skill has it move into a lane of its own first, and you approve the move once. Subagents with isolation: worktree and background sessions get lanes too. If Claude tries git worktree add or copies the repo, it's pointed to lane new instead.
Codex
codex --worktree
Or pick a worktree for a new chat in the Codex app. When the session starts, the worktree becomes a lane named codex-<id>, ready to run, and Codex is told which lane it's in. The first time, open /hooks in Codex and trust Lanes' hooks.
Cursor
agent -w fix-auth
Or start an agent in a worktree from Cursor's Agents window, or with /worktree. When it starts, the worktree becomes a lane named cursor-<name>, ready to run.
Gemini CLI
gemini -w fix-auth
Worktrees are an experimental Gemini CLI feature: switch them on with "experimental": { "worktrees": true } in its settings. When the session starts, the worktree becomes a lane named gemini-<name>, ready to run, and Gemini is told which lane it's in. Gemini CLI reads the note in AGENTS.md too.
GitHub Copilot, in the Copilot CLI or VS Code's agent mode: a session that starts in a worktree Copilot made becomes a lane named copilot-<folder> the same way. Both read Lanes' hooks from ~/.copilot/hooks, and a copy of the repo is turned down with the reason shown to the model. On Windows, updated from 0.0.8? Run lane setup --yes once to write Copilot's hooks again; lane doctor says if they need it.
Any other tool: a worktree it makes with Git becomes a lane, dependencies and all, through the Git hook lane init adds (step 6).
Optional: give agents Lanes' tools
claude mcp add lanes -- lane mcp
lane mcp is an MCP server: agents read files, outlines and search results, and make and list lanes, through tools instead of shell commands. Any MCP client can run it. Lanes adds it to no agent's settings by itself.
See them, and run the app.
lane list shows every lane with its agent's ports and folder. lane exec runs a command in one with its own PORT, VITE_PORT and LANE_URL, so the same dev server runs in two lanes at once.
Terminal (zsh)~/code/your-app
bash or zsh~/code/your-app
PowerShellC:\code\your-app
lane list
macOS
```
NAME        PORTS        STATE       PATH
fix-auth    4100-4109    ready       /Users/you/code/your-app.lanes/fix-auth
codex-a1b2  4110-4119    ready       /Users/you/.codex/worktrees/a1b2/your-app
```
Linux
```
NAME        PORTS        STATE       PATH
fix-auth    4100-4109    ready       /home/you/code/your-app.lanes/fix-auth
codex-a1b2  4110-4119    ready       /home/you/.codex/worktrees/a1b2/your-app
```
Windows
```
NAME        PORTS        STATE       PATH
fix-auth    4100-4109    ready       C:\code\your-app.lanes\fix-auth
codex-a1b2  4110-4119    ready       C:\Users\you\.codex\worktrees\a1b2\your-app
```
lane exec fix-auth -- npm run dev
Then open http://fix-auth.localhost:4100. Use your own dev command: lane exec runs whatever you give it.
In a second terminal
lane exec codex-a1b2 -- npm run dev
Codex's lane has ports 4110 to 4119, at http://codex-a1b2.localhost:4110. Both apps run side by side.
Windows
Browsers and curl.exe open *.localhost addresses. PowerShell's Invoke-WebRequest can't; use http://127.0.0.1:4100 there.
To put the port in an argument, write '$PORT' in single quotes and Lanes fills it in: lane exec fix-auth -- pnpm dev --port '$PORT'.
Or watch them all, live
lane
The terminal app lists every lane with its agent, status, URL, changed files, last test run and extra disk, and updates as things change. Under the list, "Saved by lanes" compares the disk your lanes take with a worktree plus an install for each, and counts the installs they skipped. ? shows the keys, and : or Ctrl-K opens the commands: n makes a lane, d removes one, o opens its app.
It starts laned, Lanes' background daemon, which keeps the app live and makes every change to lanes, one at a time per repo. Nothing needs it, and stopping it loses nothing: lane daemon status shows it, and lane daemon stop stops it.

Make a lane yourself.

You don't need to, but you can. A lane is a real Git worktree that starts from a clean main, with dependencies installed and a block of ten ports of its own. No branch is made, and git status and git diff work as usual.

Terminal (zsh)~/code/your-app

bash or zsh~/code/your-app

PowerShellC:\code\your-app

lane new fix-auth

macOS

Made lane fix-auth in 2.4 s (1,284 files cloned in 0.3 s).
  folder  /Users/you/code/your-app.lanes/fix-auth
  ports   4100-4109
  base    main at 4f3863f, set up just now; dependencies installed
Next:
  cd /Users/you/code/your-app.lanes/fix-auth        start your agent here, so it works only in this lane
  lane exec fix-auth -- npm run dev -- --port 4100  run the app at http://fix-auth.localhost:4100

Linux

Made lane fix-auth in 2.4 s (1,284 files cloned in 0.3 s).
  folder  /home/you/code/your-app.lanes/fix-auth
  ports   4100-4109
  base    main at 4f3863f, set up just now; dependencies installed
Next:
  cd /home/you/code/your-app.lanes/fix-auth         start your agent here, so it works only in this lane
  lane exec fix-auth -- npm run dev -- --port 4100  run the app at http://fix-auth.localhost:4100

Windows

Made lane fix-auth in 2.4 s (1,284 files cloned in 0.3 s).
  folder  C:\code\your-app.lanes\fix-auth
  ports   4100-4109
  base    main at 4f3863f, set up just now; dependencies installed
Next:
  cd C:\code\your-app.lanes\fix-auth                start your agent here, so it works only in this lane
  lane exec fix-auth -- npm run dev -- --port 4100  run the app at http://fix-auth.localhost:4100

Your times and file count will differ. The first lane takes longest: Lanes makes a clean _base copy and installs dependencies there, once. Every lane after that is a copy of it, and so are the dependencies of a lane an agent makes. Every command ends with a "Next:" block like this one.

Share it with your team.

Lanes finds your stack by itself. To set the repo up for your team, run lane init in a terminal. It asks Y/n before each step: lane.toml for teammates, the Git hook that turns any tool's worktrees into lanes, a short note on working in lanes in AGENTS.md, and installing dependencies now so the first lane is ready in seconds. It skips what's already done, ends with what's left, and running it again is safe.

Terminal (zsh)~/code/your-app

bash or zsh~/code/your-app

PowerShellC:\code\your-app

macOS and Linux

cd ~/code/your-app

Windows

cd C:\code\your-app

lane init

macOS

Setting up Lanes for /Users/you/code/your-app
Found: npm, Vite
  install  npm ci
  dev      npm run dev -- --port $PORT (usually port 5173)

? Write lane.toml with what Lanes found, so teammates get the same lanes? [Y/n] y
  ✓ wrote /Users/you/code/your-app/lane.toml
  · Claude Code, Codex, Cursor, Gemini CLI and GitHub Copilot already put their work in lanes
? Add the Git hook, so worktrees other tools make with Git become lanes too? [Y/n] y
  ✓ Git hook: worktrees other tools make become lanes
? Add a short note on working in lanes to AGENTS.md, for every agent that reads it? [Y/n] y
  ✓ AGENTS.md: a note on working in lanes
? Install dependencies now (npm ci), so the first lane is ready in seconds? [Y/n] y
  Installing in a clean copy of the repo (it can take a minute)…
  ✓ dependencies installed in a clean copy of main (14.2 s)

Next:
  git add lane.toml AGENTS.md  check it in, so teammates get the same lanes
  claude -w fix-auth           start Claude Code in a lane of its own

Linux

Setting up Lanes for /home/you/code/your-app
Found: npm, Vite
  install  npm ci
  dev      npm run dev -- --port $PORT (usually port 5173)

? Write lane.toml with what Lanes found, so teammates get the same lanes? [Y/n] y
  ✓ wrote /home/you/code/your-app/lane.toml
  · Claude Code, Codex, Cursor, Gemini CLI and GitHub Copilot already put their work in lanes
? Add the Git hook, so worktrees other tools make with Git become lanes too? [Y/n] y
  ✓ Git hook: worktrees other tools make become lanes
? Add a short note on working in lanes to AGENTS.md, for every agent that reads it? [Y/n] y
  ✓ AGENTS.md: a note on working in lanes
? Install dependencies now (npm ci), so the first lane is ready in seconds? [Y/n] y
  Installing in a clean copy of the repo (it can take a minute)…
  ✓ dependencies installed in a clean copy of main (14.2 s)

Next:
  git add lane.toml AGENTS.md  check it in, so teammates get the same lanes
  claude -w fix-auth           start Claude Code in a lane of its own

Windows

Setting up Lanes for C:\code\your-app
Found: npm, Vite
  install  npm ci
  dev      npm run dev -- --port $PORT (usually port 5173)

? Write lane.toml with what Lanes found, so teammates get the same lanes? [Y/n] y
  ✓ wrote C:\code\your-app\lane.toml
  · Claude Code, Codex, Cursor, Gemini CLI and GitHub Copilot already put their work in lanes
? Add the Git hook, so worktrees other tools make with Git become lanes too? [Y/n] y
  ✓ Git hook: worktrees other tools make become lanes
? Add a short note on working in lanes to AGENTS.md, for every agent that reads it? [Y/n] y
  ✓ AGENTS.md: a note on working in lanes
? Install dependencies now (npm ci), so the first lane is ready in seconds? [Y/n] y
  Installing in a clean copy of the repo (it can take a minute)…
  ✓ dependencies installed in a clean copy of main (14.2 s)

Next:
  git add lane.toml AGENTS.md  check it in, so teammates get the same lanes
  claude -w fix-auth           start Claude Code in a lane of its own

Then check them in

git add lane.toml AGENTS.md

Your times will differ. lane init --yes takes every default without asking. Agents, scripts and CI are never asked anything: for them it writes lane.toml and the repo's hooks, and installs nothing.

Teammates get the same lanes from lane.toml. The hooks stay on each machine, so nobody without Lanes is affected. With Husky, the Git hook is one line in .husky/post-checkout, and lane init says to add that file too. lane init --no-agents writes lane.toml only.

Use a lane by hand.
To work in a lane yourself, load its variables into your shell. Then PORT and LANE_URL are set for everything you run.
Terminal (zsh)~/code/your-app
bash or zsh~/code/your-app
PowerShellC:\code\your-app
macOS and Linux
eval "$(lane env fix-auth --shell sh)"
macOS
zsh, the macOS default, reads it as it is.
Linux
bash, zsh and other POSIX shells read it as it is.
Windows
lane env fix-auth --shell powershell | Invoke-Expression
Windows
In cmd, lane env fix-auth --shell cmd prints set lines to run instead.
Or just look
lane env fix-auth
Clean up.
Removing a lane frees its ports. When Claude Code removes its worktree, its lane goes too.
Terminal (zsh)~/code/your-app
bash or zsh~/code/your-app
PowerShellC:\code\your-app
lane rm codex-a1b2
This removes the lane's folder, changes and all. --keep-files keeps the folder and forgets the lane.
macOS and Linux
Have a worktree already? Make it a lane
lane adopt ../my-worktree --ready
Windows
Have a worktree already? Make it a lane
lane adopt ..\my-worktree --ready
--ready gives it its dependencies and .env too, like a lane from lane new.
When something's off.
lane doctor checks what could stop lanes working, and says how to fix each thing. lane logs shows what Lanes did, newest last: lanes made and removed, agents' worktrees that became lanes, and dependency installs.
Terminal (zsh)~/code/your-app
bash or zsh~/code/your-app
PowerShellC:\code\your-app
lane doctor
It checks Git, whether your disk clones files, that lane is on PATH for agents' hooks, which agents put their work in lanes, this repo's Git hook, and lanes whose folders have gone. It changes nothing, and exits 1 only when something must be fixed.
Let it fix what it can
lane doctor --fix
It fixes agents not in lanes yet, this repo's Git hook and lanes whose folders have gone, asking Y/n before each. What only you can do, like installing Git or moving a repo to a faster disk, keeps its steps.
lane logs
Inside an agent's hook, Lanes writes problems and install output here instead of into the agent's view, so this is where to look when an agent's lane didn't turn out as expected. lane logs fix-auth shows one lane.
Script it.
Every command takes --json and prints one JSON object, errors included, with a next field that says what to run next. Exit codes never change: 0 done, 1 failed, 2 wrong command line. Writes take --request-id, so a retry never makes a second lane.
Terminal (zsh)~/code/your-app
bash or zsh~/code/your-app
PowerShellC:\code\your-app
lane new fix-auth --json --request-id task-42
Every command, and every command takes --help
lane --help

Update, or remove it.

Updating keeps your lanes. Before you remove Lanes, run lane setup --yes --agents off so your agents stop calling it. Your repos and their lanes' folders stay where they are.

macOS

Update

brew upgrade lanes

Remove

brew uninstall lanes

Installed with the script? Run it again to update, and delete lane and laned from ~/.local/bin to remove it.

Linux

Update

curl -fsSL https://lanes.autter.dev/install.sh | sh

Remove

rm ~/.local/bin/lane ~/.local/bin/laned

The script updates in place. Installed with Homebrew? Use brew upgrade lanes.

Windows

Update

irm https://lanes.autter.dev/install.ps1 | iex

Remove

Remove-Item -Recurse "$env:LOCALAPPDATA\Programs\Lanes"

The script updates in place. Installed with Scoop? Use scoop update lanes and scoop uninstall lanes.

Not here yet.

Lanes is a preview. These are on the way, and the changelog says when each one lands.

Stuck? Open an issue Read the changelog

Other agents, like OpenCode, Amp and Aider, get lanes only when they make a Git worktree, through the hook `lane init` adds.
No background daemon, checkpoints or undo, and no promote to one pull request.
No database or Docker Compose project per lane yet.

Your first lanes.

Install Lanes.

Set it up once.

Let your agents make lanes.

See them, and run the app.

Make a lane yourself.

Share it with your team.

Use a lane by hand.

Clean up.

When something's off.

Script it.

Update, or remove it.

macOS

Linux

Windows

Not here yet.