Create your first lane

Start your first isolated worktree so AI tasks do not run in the primary checkout — step-by-step walkthrough with naming tips, environment setup, and verification.

Why lanes matter

A lane is ADE’s unit of parallel work. Each lane has its own git worktree, branch, port allocation, Lane Pack, and conflict tracking. Without lanes, every agent would write to the same working directory simultaneously.

The Primary Lane is your main repository checkout. It always exists and cannot be deleted. For agent-driven work, create a Worktree Lane — this keeps the primary checkout clean and lets you work manually without interference.

---

Create a lane

1. Open the Lanes view

   Click the Lanes icon (branch icon) in the left sidebar. You can also open the command palette with Cmd/Ctrl+K and choose Create Lane.

2. Click New Lane

   Click the + New Lane button at the top of the lane list. The creation dialog opens.

3. Choose a name

   Enter a short, task-oriented name. ADE uses this as both the lane identifier and the worktree directory name.

   Good names describe the work:

   • add-health-endpoint
   • fix-auth-redirect
   • refactor-payment-api

   Avoid generic names like test or feature-1 — they become confusing when you have several lanes open at once.

4. Select a base branch

   Choose which branch this lane branches from. For your first lane, select your project’s default branch (usually main or develop).

   For stacked work, you would select another lane’s branch as the base. See Stacked Lanes for details.

5. Configure the environment (optional)

   Expand the Advanced section to set:

   • Environment variable overlays — key-value pairs applied only in this lane (e.g., DATABASE_URL pointing to a test database)
   • Startup command — a command ADE runs when the lane initializes (e.g., npm run dev)
   • Port offset — override the auto-assigned port if needed

   For your first lane, the defaults are fine. You can change these later in the lane’s environment settings.

6. Create the lane

   Click Create Lane. ADE will:

   1. Run git worktree add to create the isolated directory under .ade/worktrees/<lane-name>/
   2. Initialize the lane environment (port lease, env overlay)
   3. Generate an initial Lane Pack from the branch state
   4. Add the lane to the list with idle status

   This takes 2-5 seconds for most repositories.

---

Verify the lane is ready

Once created, your new lane appears in the lane list with a grey dot (idle status). Confirm:

• The lane name and branch are correct in the list
• Click the lane to select it — the center pane shows the lane detail with a clean diff (no changes yet)
• The right inspector’s Packs sub-tab shows a freshly generated Lane Pack

You are now ready to run your first agent in this lane.

---

Naming guidance

Convention	Example	When to use
Feature prefix	feature/user-preferences	Following git-flow or similar branch conventions
Task-oriented	add-health-endpoint	Quick, descriptive — works well for most tasks
Issue-linked	linear/ENG-142	When the CTO creates lanes from Linear issues
Hotfix	hotfix/auth-redirect	Urgent fixes that need fast-tracked review

Prefer one lane per feature, fix, or experiment. If a task grows beyond what you expected, split it into stacked lanes rather than making one lane do too much. Narrow lanes have fewer conflicts and are easier to review.

---

---

Next steps

Run your first agent

Use Agent Chat for a quick task or launch a Worker run for structured execution.

Lanes deep dive

Learn about lane types, status indicators, the 3-pane layout, and health monitoring.