Branches and checkouts
Every ticket gets its own git worktree on its own branch, cut from the project’s base branch. The checkout sits beside the repository, in a sibling folder, and the agent works there and nowhere else.
Why a checkout each
Section titled “Why a checkout each”Agents never touch the branch you are on. Your own working copy is not where the work happens. You can keep editing while three tickets run.
Several tickets run at once. Two agents can change the same repository at the same time without seeing each other’s half-finished files.
The branch is the durable artefact. The checkout is scaffolding. Once a ticket has commits, the diff, the pull request and the merge all work from the repository, whether or not the folder is still there.
The branch name
Section titled “The branch name”A ticket branch is created the first time the ticket runs. The name is built from the project’s
branch prefix, the ticket’s key and a trimmed version of its title, so a ticket called “Category
filters keep their state” becomes something like ai/f1956d01-category-filters-keep-their-stat. The
prefix and the base branch are both project settings.
What is copied in, and what is shared
Section titled “What is copied in, and what is shared”If the app needs local files such as .env, enable Copy secret files into worktrees in
project settings. It is off by default for new projects. Dependencies are
installed by a setup script inferred from the repository, which finds the lockfile at the root or
in a nested workspace root; when the lockfile has not changed, the existing install is shared
rather than repeated.
Reclaiming
Section titled “Reclaiming”A finished ticket’s checkout is not thrown away. It is parked: detached from its branch, wiped clean, and kept with its dependencies and its env files, ready to be handed to the project’s next ticket with a branch switch. A one-line change after a large refactor then starts in seconds instead of after a fresh checkout and a full install.
Parking happens every five minutes, for a ticket that is Done, one that has been moved back to Backlog, one that was deleted, or one sitting in a pull request with a quiet branch. A project has a cap on how many checkouts it keeps, parked ones included, and the oldest beyond the cap are deleted. Uncommitted changes and running agents are never touched.
Settings → Worktrees lists every live and parked checkout with its project and its size. Free
space deletes build output such as dist or .next and keeps the code. Delete removes the
folder, and becomes Discard & delete when there is uncommitted work. Reclaim now runs the
sweep immediately. The worktree root is a setting; by default it is a folder named after the
repository with -worktrees appended, next to it.
The push guard
Section titled “The push guard”Agents cannot push the base branch. Herdloom installs a guard in each project’s repository that refuses it, and each agent’s permissions refuse it too. Merging into the base branch, and pushing it when the project asks for that, is done by Herdloom on your behalf, after you or a project rule asked for the merge. No agent run does it.
Worktrees settings covers the table in detail. Run the app starts a ticket’s branch on its own port, beside your own checkout.