Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ade-app.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Create a lane

The New Lane dialog walks you through three ways to start, selected by tabs at the top of the dialog.
1

Open the dialog

Click + New Lane at the top of the lane list, or press Cmd+Shift+L. The dialog description reads “Create a lane from Primary, an existing branch, or another lane.”
2

Name the lane

The name is used for both the lane identifier and the worktree directory name. Keep it task-oriented (add-health-endpoint, fix-auth-redirect) rather than generic.
3

Pick a source mode

Three tabs, one picks the base:
  • Primary — branch off the primary lane’s current HEAD. Default and best for most work.
  • Branch — attach to an existing remote or local branch. ADE checks the branch into a new worktree.
  • Child — stack onto another lane. The new lane’s base becomes the parent lane’s branch; PRs auto-target the parent.
4

Configure the environment (optional)

Expand Advanced to set:
  • Environment variable overlays — key-value pairs applied only in this lane
  • Startup command — run when the lane initializes (for example npm run dev)
  • Port offset — override the auto-assigned allocation
5

Create

Click Create Lane. ADE runs git worktree add, initializes the lane environment (port lease, env overlay, startup command), generates the first Lane Pack, and adds the lane with idle status.

​
Attaching an existing worktree

If you already have a git worktree at a custom path, use Attach Lane instead. Select the worktree directory — ADE validates it belongs to the current repo and registers it as an Attached lane.

​
Managing lanes

The Manage Lane dialog replaces the old right-click-to-rename flow for most operations. Right-click a lane in the list and pick Manage lane to open it, or use the lane’s kebab menu (⋯).

​
Rename, archive, delete

The Manage Lane dialog groups everything in one place:
  • Lane info — current name, branch, type, and worktree path
  • Archive — hides the lane from the active list while preserving history (commits, sessions, packs, checkpoints)
  • Delete — runs git worktree remove. You must type the lane name in the confirm field before the button activates
The Primary lane cannot be archived or deleted; the dialog shows a notice instead of destructive controls.
Deleting a Worktree lane runs git worktree remove and uncommitted changes in that worktree are lost. ADE warns when the lane has uncommitted work and requires you to type the lane name to confirm.
Deleted lane history (packs, checkpoints, sessions) stays in ADE’s local database for 30 days and can be browsed in the History tab. Branches are not deleted. Removing a lane does not delete its git branch — you can recreate the lane from the same branch at any time.

​
Keyboard shortcuts

ActionShortcut
New LaneCmd+Shift+L
Focus lane listCmd+1
Next laneCmd+]
Previous laneCmd+[
Open lane in GraphCmd+G
Commit staged changesCmd+Enter
Stage all changesCmd+Shift+A
Archive laneCmd+Shift+W
Regenerate Lane PackCmd+Shift+P

​
Edge cases

The Manage Lane dialog checks for uncommitted changes. If any exist, the confirmation field requires the lane name and surfaces the list of modified files. If you want to keep the work, commit, stash, or archive instead.
Deleting Primary would mean deleting your main working tree. ADE prevents this; Primary can only be hidden from the list. The Manage dialog replaces destructive controls with a “Primary lane cannot be archived or deleted” notice.
Lane name is ADE metadata. Renaming a lane in ADE does not rename the underlying git branch. If you rename the branch externally (git branch -m), ADE detects the mismatch on the next sync and prompts you to update the lane’s branch reference.
After a fast-forward merge with no new commits in the lane, the pack freshness indicator may show stale briefly before the next regeneration cycle. Regenerate from the Packs sub-tab to refresh immediately.
ADE tracks the leases it issues. If an external process is bound to a port inside ADE’s allocation range, a lane may be assigned the same port and its startup command will fail with EADDRINUSE. Use Runtime Diagnostics to spot the conflict, or set a different range under Settings → Lanes → Port Allocation.
ADE validates that an Attached lane’s worktree belongs to the current project. Attaching from a different repository fails with a validation error — each project’s ADE instance manages only its own repo.