Worktrees

How Tegment pairs every branch with its own working directory and terminals.

Tegment is built on a small, deliberate primitive: the git worktree. Every branch you care about gets its own folder and its own terminals, but they all share the same underlying repository.

Why worktrees#

You can keep several branches checked out at once and switch between them instantly, without stashing or losing terminal state. Tegment lists the repository's existing git worktrees and lets you add and remove them from the UI.

Creating a worktree#

Open the new-worktree dialog from the worktree list. You choose:

• Existing branch — check out a local or remote branch into a fresh worktree.
• New branch — create a branch and pick the base branch to fork it from.

By default the worktree folder is created next to your clone, as <repo>.worktrees/<branch>. Use Browse to put it somewhere else, or set a default location per repository in settings (see below).

After the worktree is created, Tegment copies the files listed in .worktreeinclude (see below), runs your project's post-creation commands (for example installing dependencies) and opens a terminal pane in the new directory.

New session creates worktrees the same way when you start an agent on a new or existing branch.

From an issue or pull request

If you've connected GitHub or Jira, you can create a worktree straight from an issue or PR in the sidebar. Tegment builds the branch name from the issue — for example PROJ-456-add-export — following the branch-name pattern set for that project.

Files copied into new worktrees#

A new worktree is a fresh checkout, so files git ignores, such as .env, aren't in it. List the ones a worktree needs in a .worktreeinclude file at the root of the repository, in .gitignore syntax, and Tegment copies them into every worktree it creates:

.env
.env.local
config/secrets.json

It is the same file Claude Code reads for the worktrees it creates, so one list serves both. Only files your repository ignores are copied, so a tracked file is never duplicated. The copy happens before the post-creation commands, so a command like npm install already sees them. A file that can't be copied is logged and doesn't stop the worktree from being created.

Removing a worktree#

When you're done with a branch, delete its worktree from the worktree menu. Tegment runs git worktree remove to detach it and clean up the folder; if git refuses because the worktree is busy or dirty, you can force the removal.

If a worktree is locked (git marks it locked so it can't be pruned), Tegment can unlock it again from the same menu.

Per-repository settings#

Open Settings, switch to Repository, pick the repository, and open its New worktrees page:

• Default worktree directory: where new worktrees for this repository are created. Leave it empty to use the default (<repo>.worktrees/), or point it anywhere with Browse.
• Default base branch: the branch new branches fork from when you don't pick one. Auto follows main, then master, then the first branch.
• Where a session without a ticket starts: whether New session starts work without a ticket on a new branch or in the main folder. It follows the global setting until you change it here.
• Post-creation commands: commands Tegment runs in a fresh worktree, covered in Quick actions.

When you create a worktree from a GitHub or Jira issue, the branch name comes from that integration's branch pattern, set on the repository's GitHub issues or Jira issues settings page.

How worktree rows look#

Because the Terminals section handles starting work, a worktree row is primarily a git unit. The Worktree rows card under Settings → Sidebar controls how every row is drawn:

With Hover actions set to buttons, you choose which appear: Open terminal, Open in IDE, Launch agent, and Run template. Every action stays reachable from the right-click menu whichever style you choose.