All pages
Lesson 3.1 · Organize your work · 12 min
Worktrees
Work on several branches side by side without stashing.
After this lesson you can keep several branches of one project checked out at once, switch between them in a keystroke, and open a pull request from any of them without stashing anything.
Time: 12 minutes · Works on: macOS app. Linux, Windows and the cloud workspace reach worktrees through the agent's worktree_* tools.
What a worktree is
A worktree is a second checkout of the same git repository, on its own branch,
in its own folder. Every TRMNLY project already has one: the primary
worktree, which is the project's main folder. Each extra worktree shares the
project's .git directory, so creating one is fast and takes little disk.
TRMNLY ties each terminal tab to a worktree. When you switch worktrees, the tab list in the left sidebar switches with it, and the agent's file and git tools point at the new checkout.
You need a project whose folder is a git repository. If you haven't made one yet, do the Projects lesson first.
Create your first worktree
- Select the project in the left sidebar. A pill appears at the top of the sidebar, above the tab list. It shows the active worktree's name and branch. This is the worktree selector.
- Click the pill and choose New Worktree…. You can also use the
Worktree menu in the menu bar, or press
⌃⌘N. - Type a Branch name, for example
try-new-parser. - Leave Base ref (optional) empty to branch from
HEAD, or type a branch or commit to start from. - Check the Folder. By default it's
<project>-worktrees/<branch>, beside your project folder. Use Choose… to put it somewhere else. - Leave Publish branch to remote on if you want the branch pushed to your remote right away. Turn it off for a branch that should stay local.
- Click Create.
TRMNLY runs git worktree add, then copies untracked files such as .env and
node_modules into the new folder. The new checkout is ready to run without a
fresh install. The new worktree becomes the active one.
Tip: Which untracked files get copied is set per project. Open Manage Worktrees… and look under Copied env files.
Switch between worktrees
Open a tab or two in the new worktree. Then switch back and forth:
- Click the worktree selector and pick a worktree from the list. The active
one has a checkmark. Each row shows its branch, a
*if it has uncommitted changes, and how many tabs it has open. - Or use the keyboard:
⌃⌘1through⌃⌘9switch by position, and⌃⌘]and⌃⌘[cycle forward and back. The same commands are in the Worktree menu under Switch to, Next Worktree and Previous Worktree.
Watch the tab list as you switch. Each worktree shows only its own tabs. If you click a tab that belongs to another worktree, TRMNLY makes that worktree active so the sidebar always matches the tab you're looking at.
Shells opened in a worktree get three environment variables:
$TRMNLY_WORKTREE_ID, $TRMNLY_WORKTREE_NAME and $TRMNLY_WORKTREE_BRANCH.
You can show them in your prompt to see at a glance which checkout a pane is in.
Let the agent work in a worktree
The agent follows the active worktree. Its file edits, git_* tools and bash
commands run in that worktree's folder, not the project's main folder.
- Switch to your new worktree.
- Open the Agent tab in the right sidebar.
- Ask it something that touches files, such as "Add a TODO comment to the top of the README."
- Switch back to the primary worktree and check the README there. It is unchanged.
You can also ask the agent to manage worktrees for you: "make a worktree for a branch called fix-login", "list my worktrees", or "switch to the fix-login worktree". Creating, switching, renaming and removing ask for your approval.
Tip: If you use Claude Code connected to TRMNLY, it has its own worktree tool that doesn't know about projects. In a TRMNLY project, ask it to use TRMNLY's
worktree_createandworktree_switchinstead. A worktree made another way can be registered withworktree_adopt.
Open a pull request
- With your branch committed, click the worktree selector.
- Choose Open PR…. TRMNLY pushes the branch and opens a pull request. Tick Open as draft if it isn't ready for review.
- Once a PR exists, the selector shows View PR #N instead.
Open PR… isn't offered on the primary worktree.
For more git actions, open Manage Worktrees…. Each row has a git menu with Commit & Push…, Push Branch, Open PR…, Merge PR & Clean Up…, Refresh PR Status and Forget PR. The same sheet lets you rename a worktree, reveal it in Finder, or remove it.
Clean up
When a branch is merged, remove its worktree:
- Open Manage Worktrees….
- Use Merge PR & Clean Up… to merge and remove in one step, or remove the worktree from its row.
Removing a worktree deletes its folder. TRMNLY asks you to confirm first, but push or commit anything you want to keep before you do. The primary worktree can never be removed.
Check yourself
- You have two worktrees, and switching with
⌃⌘]changes the tab list. echo $TRMNLY_WORKTREE_BRANCHin a pane prints that worktree's branch.- An agent edit made in one worktree doesn't appear in the other.
- Manage Worktrees… lists both, and you can find the git menu on a row.