Skip to main content

Worktrees

This is the agent's worktree tool: when one AdaL session needs to do parallel work, it puts each piece of work in its own worktree, an isolated checkout on its own branch. All you need to do is ask:

the retry bug and the auth refactor are unrelated — work on both at once

AdaL creates a worktree per task, works inside it, and tells you where each one is. In Engineer mode it puts a worker in each and merges the results back.

How it works​

Worktrees live in .agents/worktrees/<name>/ on branch worktree-<name>. The agent's tool has four actions: create, list, remove, and cleanup.

Setup files are copied into each new worktree so it is ready to run. With no config, AdaL copies the common env files (.env, .env.*, .env.local, .env.*.local). To control what gets copied, commit a .agents/worktrees.toml in your project root:

[copy]
include = [".env", ".env.*", "config/secrets.json"]

include accepts a list or a single string. Add .agents/worktrees/ to your .gitignore so worktree contents do not show up as untracked files in your main checkout. Keep .agents/worktrees.toml committed — which files a fresh checkout needs is a property of the project, not of your machine.

The .agents/ convention travels with your AGENTS.md, so a worktree created here is usable by any agent, not just AdaL.

Cleanup​

cleanup is an explicit action, not a background timer: ask AdaL to clean up when you are done, and it removes the worktrees whose work has landed and reports what it did. It will not remove one holding uncommitted changes or unpushed commits unless you tell it to.

Running AdaL in a worktree yourself​

The worktree tool is agent-only. To run AdaL in a worktree manually, use native git:

git worktree add .agents/worktrees/feature-auth -b worktree-feature-auth
cd .agents/worktrees/feature-auth && adal

git worktree list
git worktree remove .agents/worktrees/feature-auth

Running adal inside a worktree works exactly like running it anywhere else — a worktree is just a directory.