All pages
Docs · Start here
Worktrees
Availability: macOS (the sidebar selector) · Linux, Windows and the cloud workspace through the worktree_* tools, which are in the portable universal tier — see Platforms. A worktree can also live on another machine (below).
A worktree is a git checkout owned by a project. Every project has one
primary worktree (the project's main folder). Additional worktrees are
parallel checkouts on different branches that share the project's .git
directory — cheap to create, instantly switchable, and isolated from each
other on disk.
Use worktrees when you want to keep a long-running branch hot while you review a PR on another, run two stacked branches side by side, or let the agent fan out to a feature branch without disturbing what you're on.
Where it lives
The worktree selector is a pill at the top of the left sidebar, just above the tab list, visible whenever a project is selected. It shows the active worktree's name and current branch.
Click the pill for:
- A list of existing worktrees (checkmark on the active one, each
with its branch, a
*dirty marker, and its open-tab count) - Open PR… / View PR — push the active worktree's branch and open a pull request (with a draft option), or jump to the PR it already tracks. Not offered on the primary worktree.
- New Worktree… — modal: branch name, optional base ref, target folder (auto-derived default), and a Publish branch to remote toggle (on by default)
- Manage Worktrees… — table of every worktree with rename, reveal in Finder, and remove actions, plus settings for the worktrees folder and env-copy globs. Each row also has a git menu: Commit & Push…, Push Branch, Open PR…, Merge PR & Clean Up…, Refresh PR Status, and Forget PR.
The same actions sit in the Worktree menu, with shortcuts: ⌃⌘N opens
New Worktree…, ⌃⌘1–⌃⌘9 switch by position, and ⌃⌘] / ⌃⌘[
cycle forward and back.
Creating a new worktree runs git worktree add under the hood and
APFS-clones untracked files matched by your env-copy globs (.env,
node_modules, .next, …) so the new checkout is immediately usable
without a fresh install. New worktrees land in <project>-worktrees/<branch>
beside the project folder; a project that already has a
<project>-workspaces/ folder from an earlier release keeps using it.
How tabs scope
Each tab is tagged with both a project id and a worktree id. The sidebar's tab list filters to only the active worktree's tabs — switching worktrees hides the previous list and shows the new one. If a tab was created before the project had any extra worktrees, it carries no worktree id and belongs to the primary worktree by convention.
Focusing a tab tagged with an inactive worktree auto-mirrors that worktree into active state, so the sidebar always reflects the focused tab's checkout.
Agent integration
The agent's tool context is worktree-pinned: file writes,
git_*, bash, and project-scoped tools target the active worktree's
folder, not the project's primary folder. Switching worktrees mid-turn
re-pins.
Seven agent tools manage worktrees directly:
| Tool | Approval | Use |
|---|---|---|
worktree_list |
no | Enumerate worktrees (id, name, branch, folder, active); also reports checkouts git knows about that TRMNLY hasn't registered (first 10 named, the rest counted; verbose lists all) |
worktree_create |
yes | Create a worktree on a new branch; copies env files; becomes active |
worktree_switch |
yes | Set the active worktree; sidebar tabs re-filter |
worktree_rename |
yes | Rename the label; optionally renames the branch via git branch -m |
worktree_remove |
yes | Delete the worktree + folder. Primary cannot be removed. |
worktree_adopt |
yes | Register an existing git worktree that TRMNLY doesn't know about; paths adopts several in one call |
worktree_merge_cleanup |
yes | Merge the worktree's PR and remove the worktree |
Tools that name an existing worktree take worktree_id, name, or
branch. When the agent opens a pull request from a worktree with
gh_pr_create, the PR's number, URL and state are recorded against that
worktree, so a later worktree_list says which branch is waiting on review
and which has merged.
A worktree on another machine
worktree_create, worktree_list and worktree_remove take a host:
a saved SSH host name from the Conn sidebar, the same
names ssh_exec takes. With it the worktree lives on that machine, reached
with that host's port, identity and jump chain. Two more arguments become
paths as that machine spells them: source_folder, the repository
there (required with host, ignored without), and target_folder,
where the worktree should go (required with host — there is no local
project folder to derive one from).
A remote worktree is not registered as a project workspace, because it has
no local folder: the sidebar selector doesn't show it, and you work in it
with ssh_exec, or open it in the Files sidebar through its
host button. project_list shows every project and which one the caller is
bound to; pass project_id to reach another. These tools were called
workspace_* in earlier releases — the old names (and workspace_id)
still execute as aliases so saved runbooks keep working, but they are no
longer advertised. "Workspace" now means only the cloud sandbox
(Remote).
Claude Code and other agents
Claude Code has its own worktree tool, EnterWorktree, and it fires
whenever someone says "worktree" — but it knows nothing about projects,
env-file copies, or the sidebar. So one rule, stated everywhere an agent
reads (the trmnly-worktrees skill, TRMNLY.md, and here):
In a TRMNLY project, create and switch worktrees with
mcp__trmnly__worktree_create/worktree_switch(they register the checkout with the project, copy env files, and keep the sidebar and tools pointed at it). If you already made a worktree another way (EnterWorktree,git worktree add), register it withmcp__trmnly__worktree_adopt. Do not useEnterWorktreeor rawgit worktree addin a TRMNLY project when the bridge is connected.
Three things carry that rule to a session:
- The
trmnly-worktreesskill. The MCP bridge installs it into~/.claude/skills/with the other five. Its description names worktrees, branches and PRs, so Claude Code loads it for exactly the requests its built-in would otherwise take, and it walks through the two common flows (work on a PR beside the current branch; adopt a worktree made by hand). TRMNLY.md, wired in. Add TRMNLY.md to current project (Settings → AI Agent → Project context) and the auto-add setting writeTRMNLY.mdif it is missing (never overwriting — the Project notes section is yours), make sureCLAUDE.local.mdcontains the line@TRMNLY.md, and add both names to the repository's.git/info/exclude. Claude Code loadsCLAUDE.local.mdalongsideCLAUDE.md; a standaloneTRMNLY.mdis never read, and the trackedCLAUDE.mdis never touched. The exclude is resolved through the common git dir, so it works from inside a linked worktree, and nothing tracked changes. New worktrees get both files copied from the primary checkout, and the installer runs on the new checkout when auto-add is on.- Linux and Windows.
trmnly-core-mcpinstalls the skill bundle into~/.claude/skillson start and does the project wiring withtrmnly-core-mcp --setup-project <path>; register it withclaude mcp add trmnly -- trmnly-core-mcp. The portable core runsworktree_list,worktree_create,worktree_removeandworktree_adoptagainst git directly.worktree_switch,worktree_renameandworktree_merge_cleanupreport themselves unimplemented there — they need a project store the core doesn't have yet, so the answer on those hosts is tocdinto the pathworktree_createreturns.
Quirks
- The primary worktree is never removable; it tracks the project's folder path itself.
- Git state (current branch, dirty status) is cached and refreshed in
tiers: the current project and any project with a live tab every 15
seconds, the rest every five minutes (stalest first, four per tick), and
a folder with no
.gitat or above it is never probed. A watcher on each repository's git directory — worktrees included — picks up commits, checkouts, staging and fetches within seconds, and becoming the current project refreshes it at once. Every probe runs withGIT_OPTIONAL_LOCKS=0, so a poll can never make your owngit commitfail withindex.lock: File exists. - Removing a worktree deletes its directory — make sure uncommitted work is pushed first. The remove action confirms before it runs.
- Shells opened for a project export
$TRMNLY_WORKTREE_ID,$TRMNLY_WORKTREE_NAMEand$TRMNLY_WORKTREE_BRANCH, so your prompt can show which checkout a pane belongs to. The older$TRMNLY_WORKSPACE_*names are still exported for one more release. help_read("workspaces")still opens this topic.