Worktrees

A worktree is a separate Git working directory connected to the same repository.

Use one when a stream of work needs its own branch and file checkout. That is especially useful for agent work because two agents editing the same directory can step on each other quickly.

What a worktree gives you

A worktree gives a branch its own directory.

That means you can:

• Keep your main checkout clean while an agent experiments.
• Run two unrelated branches side by side.
• Compare two approaches without constantly stashing changes.
• Review or discard one branch without disturbing another.

It is still the same repository history underneath. Git knows the worktrees are related; the file edits just happen in separate directories.

What it does not give you

A worktree is not a sandbox.

Commands in a worktree still run on your machine. They can use the same network, credentials, package caches, databases, and local services available to your user account.

Use a worktree to separate Git edits. Do not use it as a security boundary.

When to use one

Use a worktree when the work has a clear branch boundary:

• One agent is fixing a bug while another updates docs.
• You want to test two implementations of the same idea.
• A task should stay away from your base checkout.
• You need a review lane while a dev server keeps running elsewhere.

Avoid worktrees when the split is fake. If two agents need to edit the same files at the same time, the safer move is usually sequential work: finish one branch, review it, then rebase or restart the next one.

Worktrees in Coldtea

Coldtea can keep a worktree visible as its own workspace lane. The tab, terminal pane, editor, and brew should all make it clear which path and branch you are using.

Where configured, worktree setup scripts can prepare the new directory so an agent does not start from a half-ready checkout. Keep those scripts boring and repeatable. If setup writes secrets or machine-specific files, review that before handing the worktree to an agent.

Review and cleanup

Treat each worktree like a small branch with a finish line:

1. Read the task and plan.
2. Inspect the diff in that worktree.
3. Run the checks for that branch.
4. Merge, continue, or discard the branch.
5. Remove the worktree after you no longer need that directory.

Do not let old worktrees pile up. Stale directories make it too easy to run commands in the wrong place.

The rule to remember

Worktrees isolate Git working directories, not machine permissions.

That one sentence should shape how you use parallel agents. Separate the branches, keep the checks visible, and review one diff at a time.

Next: run parallel agents for the workflow version of this concept.