Headmaster by GCAP Labs

A git worktree is a second checkout of the same repository, with its own folder and its own branch. Give each agent its own worktree and several of them can work on one project at once without overwriting each other's files.

Why use them

If two agents share one checkout, one can delete or rewrite files the other is using, and you cannot tell which change came from which experiment. With a worktree each agent gets:

its own branch and working folder,
its own checkpoint history for rollbacks.

Headmaster treats the folder you start it in as the project, so starting in a worktree keeps all the agent's reading, editing and commands inside that worktree.

Start a session in a fresh worktree

From inside your repository:

headmaster -w

Headmaster creates a disposable worktree under .worktrees/ in the repo, on its own new branch, and runs the whole session there. Combine it with a single request:

headmaster -w -z "Fix issue 123"

Open several terminals and run headmaster -w in each to run agents in parallel. Each gets its own worktree.

Headmaster checks the worktree out without running the repository's own hooks or filters. If the repo uses Git LFS you get pointer files, so run git lfs pull inside the worktree if the session needs the real contents.

From inside a chat

In an interactive terminal session, /worktree new my-experiment creates .worktrees/my-experiment/ and moves the session into it. Leave out the name for a random one. /worktree shows the current tree and /worktree list lists them all.

Your own worktrees

You can also create them with git and start Headmaster in them:

git worktree add ../repo-experiment feature/experiment
cd ../repo-experiment
headmaster

When the session ends

If the tree is clean and its commits are pushed, it is removed. If it has uncommitted changes or unpushed commits, an interactive session asks:

Keep the worktree. The default. Nothing changes.
Archive and remove it. The full state is saved, the tree is removed, and the headmaster worktree restore command is printed.
Remove it and discard the changes. Only if you pick it yourself.

One-shot runs, scheduled tasks, messaging sessions and anything without a terminal never ask. They keep the tree, and the cleanup below handles it later.

Automatic cleanup

At startup and every six hours, Headmaster checks the worktrees it created and tidies the idle ones:

Tree	What happens
Idle past its time limit, clean and merged or pushed	Removed.
Idle past its time limit, with uncommitted or unpushed work	Archived, then removed.
In use, or touched recently	Never touched.
Holds submodules, nested repositories or oversized untracked files	Kept, because it cannot be archived safely.

An archive holds the tree's commit, staged changes, unstaged changes and untracked files. Files your .gitignore excludes, such as node_modules, are not saved. A branch that exists on a remote is kept. Otherwise the archive holds its commits.

The worktree command

headmaster worktree list
headmaster worktree prune --dry-run
headmaster worktree restore <name>

Command	What it does
`list`	Show every tree with age, size, verdict and reason. This is the default. Aliases: `ls`, `audit`.
`prune`	Remove safe trees and delete fully merged local branches.
`restore <name>`	Recreate an archived tree, with its staged and untracked files.

Options:

Option	For	What it does
`--repo`	all	Use this repository instead of the current one.
`--json`	`list`, `prune`	Machine-readable output.
`--older-than DAYS`	`list`, `prune`	Treat trees younger than this as keep.
`--dry-run`	`prune`	Show the plan and change nothing.
`--trees-only`	`prune`	Leave local branches alone.
`--branches-only`	`prune`	Leave worktrees alone.
`--path`	`restore`	Restore somewhere other than the original place.

Run prune --dry-run first to see every decision and the reason for it. Restore brings the branch back when it is missing or still at the archived commit. Otherwise the tree comes back detached at that commit.

Settings

In the worktrees section of your config file (headmaster config path prints its location):

worktrees:
  archive_dirty: true
  archive_max_file_mb: 50
  archive_retention_days: 30
  max_total_gb: 0

Setting	What it does
`archive_dirty`	`false` means trees with unsaved work are never removed.
`archive_max_file_mb`	Untracked files larger than this are not archived, and their tree is kept.
`archive_retention_days`	Archives older than this are deleted. `0` keeps them forever.
`max_total_gb`	Optional space budget for idle trees. The oldest are archived and removed first. `0` means no budget.

Good practice

One worktree per experiment, with a branch named for it.
Commit often. Commits are your milestones, and checkpoints cover the edits in between.
Start agents from a worktree folder, not the main checkout, so each one has a clear scope.
Sub-agents can also work in their own worktrees, so parallel children do not collide. A clean tree is removed when the child finishes, and one with changes is archived with its branch kept for you to merge.

Git worktrees