Worktrees

The Worktrees feature gives a branch its own checkout and keeps that lane visible in Coldtea.

Use it when an agent needs to work without touching your base checkout, or when several tasks need separate branches at the same time.

Create a worktree

Coldtea can create a worktree from a selected base branch or, in detached-HEAD cases, from the current commit. The start modal previews the derived worktree name and branch before anything launches.

For task batches, Coldtea can create one worktree per task. Each worktree keeps its own generated name so the sessions do not pile into the same directory.

Check the base branch before you confirm. A worktree created from the wrong branch is still a wrong branch.

Worktree mode

A worktree tab shows a worktree banner with the base project, base branch, worktree branch, and script status. Use that banner when you need to answer “where am I?” before prompting an agent.

The banner also exposes actions such as:

• Open the base project.
• Copy local-only files from the base project.
• Configure scripts.
• View, rerun, or stop setup and run panes.
• Finish or delete the worktree.

The exact actions depend on the worktree state and configured scripts.

Setup, run, and teardown scripts

Worktree scripts are optional. When configured, Coldtea can run setup after creating a worktree, run a project command from the worktree, and run teardown before deletion.

Scripts run in visible panes. If a setup script fails, inspect it before handing the worktree to an agent. If teardown fails, Coldtea keeps the worktree intact unless you explicitly skip teardown and delete anyway.

Configure shared scripts in .coldtea/config.json and local overrides in .coldtea/config.local.json.

Copy local-only files

Some repos need files that are not tracked by Git: local env files, generated config, test data, or editor settings. The copy-local-files action scans for local-only entries in the base project and lets you choose what to copy into the worktree.

Be selective. Copy what the worktree needs, not every private file you happen to have.

Finish or delete

Finishing a worktree is a review moment. Coldtea can show branch status, uncommitted changes, and push availability before you decide what to do next.

Deleting a worktree removes the worktree directory and unregisters it from Coldtea. Coldtea then attempts best-effort cleanup of the linked branch when it has enough Git context. The base project stays untouched.

If Keep this worktree if it has uncommitted changes is enabled, Coldtea blocks deletion when it detects uncommitted tracked changes. Untracked local files are outside that guard, so check anything local-only before deleting.

What worktrees do not isolate

A worktree separates Git working directories. It does not isolate machine permissions, credentials, local services, package caches, or databases.

Use worktrees to keep branches from stepping on each other. Do not treat them like containers.

Next: read the worktree concept, configure worktree scripts, or run parallel agents.