> ## Documentation Index
> Fetch the complete documentation index at: https://ade-ac1c6011-dependabot-github-actions-actions-cache-6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Lanes

> A lane is ADE's name for a git worktree — one isolated branch and working copy per task, so agents work in parallel without colliding.

A **lane** is ADE's name for a git worktree: an isolated branch and working copy for a single task. Each lane has its own files, branch, chat and terminal sessions, processes, diff, and PR — so several agents can work in the same repository at once without writing over each other or your main checkout.

<Frame caption="Every task gets its own worktree — describe it and ADE creates the branch.">
  <img src="https://mintcdn.com/ade-ac1c6011-dependabot-github-actions-actions-cache-6/mZiHD0-x8whDsXL3/media/demos/auto-worktrees.gif?s=a3edf73e679a045de690ffcbf2e6e2e6" alt="Auto-create a git worktree from a task" width="620" height="389" data-path="media/demos/auto-worktrees.gif" />
</Frame>

## The primary lane vs. your lanes

When you open a repository, your existing checkout — the repo root — becomes the **primary lane**. It always exists and can't be deleted or restacked. Agents *can* work in it, but it's your real working tree, so the safer habit is to leave the primary lane alone and do agent work in fresh lanes.

Everything else is a lane you create. Each new lane is its own git worktree under `.ade/worktrees/`, completely isolated from the primary checkout and from other lanes.

<Note>
  You don't pick a "lane type" — the primary lane is just your repo root, and every other lane is a worktree. What differs is **how** you bring a lane into being.
</Note>

## Ways to create a lane

<CardGroup cols={2}>
  <Card title="New worktree off a branch" icon="code-branch">
    Branch a fresh worktree from your default branch — or any other branch. This is the default, and the safest place for agent work.
  </Card>

  <Card title="Child lane (stacked)" icon="layer-group" href="/lanes/stacks">
    Branch a lane off another lane instead of `main` to build dependent work as a stack. ADE calls these **child lanes**.
  </Card>

  <Card title="Import an existing branch" icon="download">
    Pull a branch you already have — local or remote — into a managed worktree, PR pills and all.
  </Card>

  <Card title="Attach an external worktree" icon="link">
    Already made a `git worktree` outside ADE? Attach its path and ADE tracks it without ever moving or cleaning it.
  </Card>
</CardGroup>

## The same lanes, everywhere

Lanes sync across every surface. Start one on the desktop, continue it in the terminal, check on it from your phone.

<Tabs>
  <Tab title="Desktop">
    <Frame caption="The Lanes tab on macOS.">
      <img src="https://mintcdn.com/ade-ac1c6011-dependabot-github-actions-actions-cache-6/mZiHD0-x8whDsXL3/media/landing/showcase/worktrees-desktop.webp?fit=max&auto=format&n=mZiHD0-x8whDsXL3&q=85&s=46a10ca9f3e2bef28b2608e09be393c1" alt="Lanes on the desktop" width="2094" height="1169" data-path="media/landing/showcase/worktrees-desktop.webp" />
    </Frame>
  </Tab>

  <Tab title="Terminal">
    <Frame caption="The same lanes in ade code.">
      <img src="https://mintcdn.com/ade-ac1c6011-dependabot-github-actions-actions-cache-6/mZiHD0-x8whDsXL3/media/landing/showcase/worktrees-tui.webp?fit=max&auto=format&n=mZiHD0-x8whDsXL3&q=85&s=d9c68571b3050cd9517276dc79e906e0" alt="Lanes in ade code" width="2027" height="1119" data-path="media/landing/showcase/worktrees-tui.webp" />
    </Frame>
  </Tab>

  <Tab title="iOS">
    <Frame caption="Browse and create lanes from your phone.">
      <img src="https://mintcdn.com/ade-ac1c6011-dependabot-github-actions-actions-cache-6/mZiHD0-x8whDsXL3/media/landing/showcase/worktrees-mobile.webp?fit=max&auto=format&n=mZiHD0-x8whDsXL3&q=85&s=bfb2ec48ee17d73eb8e99d4a3c5762d9" alt="Lanes on iPhone" width="300" data-path="media/landing/showcase/worktrees-mobile.webp" />
    </Frame>
  </Tab>
</Tabs>

## What's isolated to a lane

A lane is more than a branch — it's a full parallel workspace.

<Columns cols={2}>
  <Card title="Code & branch" icon="folder-tree">
    A dedicated worktree and branch. Stashes, rebases, and merges stay local to the lane.
  </Card>

  <Card title="Sessions" icon="comments">
    Chats, terminals, and CLI sessions run scoped to the lane's worktree.
  </Card>

  <Card title="Processes & ports" icon="server">
    Dev servers and tests get their own port range and preview, so lanes don't fight over `3000`.
  </Card>

  <Card title="Diff & PR" icon="code-pull-request">
    A clear diff, conflict risk, and a PR link — review and ship each lane on its own.
  </Card>
</Columns>

## The lane lifecycle

<Steps>
  <Step title="Create">
    Branch a worktree from your default branch, stack a child lane, import a branch, or attach an external worktree.
  </Step>

  <Step title="Work">
    Open chat, terminals, Files, or Run — all scoped to the lane.
  </Step>

  <Step title="Review">
    Inspect the diff, tests, proof, History, and conflict risk.
  </Step>

  <Step title="Ship">
    Commit, push, open a PR, merge, then archive or delete the lane.
  </Step>
</Steps>

<Frame caption="The worktree graph shows stack order, PR links, and merge risk at a glance.">
  <img src="https://mintcdn.com/ade-ac1c6011-dependabot-github-actions-actions-cache-6/mZiHD0-x8whDsXL3/media/features/worktrees/worktree-graph.webp?fit=max&auto=format&n=mZiHD0-x8whDsXL3&q=85&s=1d2047fcff17bf8d94ddbd9d0796111f" alt="The worktree graph" width="1280" height="696" data-path="media/features/worktrees/worktree-graph.webp" />
</Frame>

<AccordionGroup>
  <Accordion title="Manage lanes from the terminal" icon="terminal">
    Every lane action is also available from the `ade` CLI and `ade code`:

    ```bash theme={null}
    ade lanes list --text                 # list lanes in the active project
    ade lanes create "fix-checkout-flow"  # branch a new worktree lane
    ade lanes delete <lane-id> --force    # tear down a merged or abandoned lane
    ```

    Run `ade lanes --help` to see every flag.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Create lanes" icon="plus" href="/lanes/creating">
    Every way to start a lane, in detail.
  </Card>

  <Card title="Stack lanes" icon="layer-group" href="/lanes/stacks">
    Build child-lane chains and reviewable stacks.
  </Card>
</CardGroup>
