Interface Tour
When you open Arborist you'll be greeted by a window that is split into 3 sections:
- On the leading side is the sidebar, containing all of your repositories and their worktrees
- In the middle is the "command center", where you can run tools and commands. Read more on those in their respective pages.
- The trailing side is an inspector for the actively selected worktree. It has basic information about the branch checked out, as well as a list of the found AI chat transcripts from that worktree.
Arborist remembers the worktree or repository you had selected, and where the sidebar was scrolled, so it opens right where you left off.
Adding a Repository
Adding a repository to Arborist is as easy as either opening it via the File -> Add Repository command (cmd-O) or dragging and dropping it on to the Arborist window. Once the repository is loaded it will appear in the sidebar, and Arborist will pick up any worktrees already associated with it.
The first time you open Arborist it will also suggest repositories it finds on your Mac. Read more about that in setting up Arborist.
The Sidebar
Each repository in the sidebar groups its worktrees into sections:
- Primary is the repository's main checkout.
- Pinned holds the worktrees you've pinned to the top.
- Worktrees holds everything else.
- Agents holds worktrees created by AI agents, when you've turned that grouping on (see below).
Pinning Worktrees
Pin the worktrees you come back to most so they stay at the top of their repository. Select a worktree and choose Pin Worktree from the Worktree menu (or use the opt-cmd-P keyboard shortcut), or use the worktree's context menu. Choose Unpin Worktree to send it back to the Worktrees section. Pins are saved per repository, and pinned worktrees are never removed by cleanup.
Status Badges
A worktree row shows a badge when Arborist thinks it might be stale:
- Merged means the worktree's pull or merge request was merged.
- Closed means its request was closed without merging.
- Gone means its branch was deleted from the remote.
- Inactive worktrees show how long it has been since their last commit.
Merged and Closed require a service account for the repository's host. You can choose which of these rules apply, and how long counts as inactive, in Cleaning Up Worktrees.
When a worktree isn't stale, its row instead shows when a command is running in it or how many commits it is behind its upstream branch.
Agent Worktrees
Tools like Claude Code, Codex, and Copilot often create worktrees of their own. Arborist recognizes the standard places these agents put them. If you'd like to keep them apart from the worktrees you made yourself, open the Worktrees pane in Settings and check "Group agent worktrees separately." Recognized agent worktrees then move into the Agents section. Pinned agent worktrees stay in Pinned.
If your agents create worktrees somewhere else, add that folder under AI Agent Search Paths in the same pane. Worktrees in those folders and their subfolders are treated as agent worktrees right away.
Repository Info
Click a repository's name in the sidebar (or select a worktree and choose Show Info from the Repository menu, cmd-I) to see that repository's details. The main area lists every worktree with its last commit, linked pull or merge request, and status, and it's where you clean up worktrees. The inspector shows how the repository is laid out on disk, a count of worktrees by section, and the repository's stale-worktree rules. For Grove repositories, this is also where you'll find the Grove configuration.
Finding a Worktree
Choose Filter Worktrees from the Worktree menu (cmd-F) to narrow the sidebar down to matching repositories and worktrees. To quickly switch between worktrees in the selected repository, use the Switch to Worktree submenu in the Repository menu. Its first ten worktrees have the keyboard shortcuts cmd-0 through cmd-9.