Skip to content
wrktr docs

Branches and worktrees

Every change on wrktr is a branch, and every branch you work on locally has a git worktree of its own under .wrktr/worktrees/<branch>. Give each agent its own branch, and they can work side by side in one repo without touching each other’s files.

Terminal window
wrktr branch new copy-hex           # .wrktr/worktrees/copy-hex
wrktr branch new lock-colors        # a second agent, at the same time
wrktr branch ls                     # the worktrees on this machine

.wrktr/ is kept out of git.

What branch new does

Section titled “What branch new does”
  1. Fetches the default branch and starts the new branch from it, so a local copy that fell behind is never the base. Offline, it starts from the local copy. --from <ref> starts it somewhere else.
  2. Copies the gitignored files listed in wrktr.json copy (such as .env) into the worktree.
  3. Runs wrktr.json’s install command there (such as npm ci).
  4. Pushes the branch. From then on the daemon keeps it in sync.

A name used before is reused only if that branch is fully merged.

A branch’s life

Section titled “A branch’s life”

A branch is in progress until it lands or is closed.

  • Landed: its head merged into the default branch. See Landing. New commits on a landed branch make it a change in progress again.
  • Closed: set aside without landing (wrktr branch close). Its agents and checks stop; its history, reviews and threads stay. wrktr branch reopen brings it back.
  • Experiment: a spike or prototype that never lands (wrktr branch new <name> --experiment, or wrktr branch experiment). --off lets it land again.

Descriptions

Section titled “Descriptions”

The review agent writes each branch a description and keeps it current as the branch moves: a title, a summary, the changes by area, risks, and how to check it. wrktr branch show prints it.

Overlaps

Section titled “Overlaps”

wrktr warns early when two branches in progress change the same files, before they conflict. The web app shows it on each branch, and GET …/branches/state returns it as overlaps.

Cleaning up

Section titled “Cleaning up”
Terminal window
wrktr branch rm copy-hex            # remove the worktree (--force with uncommitted changes)
wrktr branch rm copy-hex --delete   # and delete the branch, on wrktr and locally

wrktr land --rm removes the worktree after landing.