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 with mcp__trmnly__worktree_adopt. Do not use EnterWorktree or raw git worktree add in a TRMNLY project when the bridge is connected.

Three things carry that rule to a session:

  • The trmnly-worktrees skill. 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 write TRMNLY.md if it is missing (never overwriting — the Project notes section is yours), make sure CLAUDE.local.md contains the line @TRMNLY.md, and add both names to the repository's .git/info/exclude. Claude Code loads CLAUDE.local.md alongside CLAUDE.md; a standalone TRMNLY.md is never read, and the tracked CLAUDE.md is 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-mcp installs the skill bundle into ~/.claude/skills on start and does the project wiring with trmnly-core-mcp --setup-project <path>; register it with claude mcp add trmnly -- trmnly-core-mcp. The portable core runs worktree_list, worktree_create, worktree_remove and worktree_adopt against git directly. worktree_switch, worktree_rename and worktree_merge_cleanup report themselves unimplemented there — they need a project store the core doesn't have yet, so the answer on those hosts is to cd into the path worktree_create returns.

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 .git at 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 with GIT_OPTIONAL_LOCKS=0, so a poll can never make your own git commit fail with index.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_NAME and $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.