Create a worktree
Click + in the sidebar or press Cmd-N to give a branch its own checkout. Choose a repository and base, then describe the task.

Start creates the worktree and sends your task to the agent. The first line names the item. For an empty checkout, leave the message blank and click Create worktree. Closing the form keeps your draft until you quit.
- Repository defaults to the current or last-used repository. The menu follows configuration order, marks local-only repositories, and lets you add a folder.
- Base lists local and remote-tracking branches from your clone, or branches from GitHub when there’s no local clone.
- New branch combines
branch_prefixand the first five words of your task. Perch adds a suffix to resolve a generated name conflict. If you typed the name, it asks you to choose another.
Worktrees go under ~/.perch/worktrees/ by default, named for the repository and the branch. To put new worktrees elsewhere, set worktrees_dir.
When you choose a repository with a local root in New worktree, Perch creates the branch in your clone. Run git worktree list there to find the checkout. It shares your remotes and Git configuration. Perch fetches the base branch using your credentials. If Git needs an interactive password or passphrase, Perch uses the base already on disk and tells you its age.
In your clone, Perch creates the branch and worktree record, fetches the base, deletes the branch when you choose Delete, and pushes and sets its upstream when you open a PR or choose Push. A GitHub repository without a local root uses a clone managed by Perch. Start Work on a GitHub issue or PR also uses Perch’s clone. Starting from a local worktree uses that repository.
Start work from an item
Open an item’s details and choose Start Work on the Worktree row or its menu. You can also use the sidebar row’s menu, including on an issue or PR notification. The starting branch depends on the item.
- Issue. Perch creates
perch/issue-<n>from the default branch. - Pull request. Perch creates
perch/pr-<n>-workfrom the PR checkout, including unpushed commits, or from the head on GitHub if there’s no checkout. The diff uses the original PR’s base, so it includes the original changes. This also works on forks and other people’s PRs. - Worktree. Perch starts from its current commit and adds a suffix such as
-2to the branch name.
For an issue or PR, Perch prepares a prompt in the new worktree. Click Start Work on the original item again to reopen the same worktree, or find it under In Perch. A PR opened from it includes Closes #<n> so merging closes the original issue or PR. Merged PRs and archived items have no Start Work action.
Starting from a notification opens or creates its Perch item first. The action is disabled once Perch sees that the PR merged or the issue closed. If you removed the PR’s worktree, open the PR to restore it first.
Keeping work safe
Before removing or updating a worktree, check for files and commits that exist only there.
- Delete asks for confirmation and counts commits with no other branch, tag, remote-tracking branch, or Perch ref pointing to them. For branches pushed from Perch’s clone, Perch recognizes the push when the PR brings its head commit back.
- Archive keeps the branch and commits but removes the checkout. Perch names ignored files such as
.envand asks before removing them. It can archive PR checkouts unopened for 14 days. Worktrees without PRs have no age limit. - A PR checkout follows the PR head only when its current commit belonged to the PR. Unpushed commits or uncommitted changes keep it in place. Perch marks it stale.
- Your own worktree stays at the commit you checked out. The Branch row shows
3 unpushed,2 behind PR, both, orPR head not fetched. Counts use local Git data. Submit review and Merge become available when the checkout matches GitHub. - Update branch fetches a missing PR head or fast-forwards a worktree that is only behind. Perch uses your credentials in your clone and its token in a managed clone. Unpushed commits stay in place. If the update would overwrite a changed file, Perch stops.