---
title: "Worktrees"
source: https://docs.autohand.ai/working-with-autohand-code/worktrees
---

# Worktrees

Work on multiple features and branches at the same time without switching context. Autohand Code CLI manages worktree creation, syncing, and cleanup so you can focus on shipping.

## What are worktrees

Git worktrees let you check out multiple branches of the same repository into separate directories at the same time. Instead of stashing your work or committing half-finished changes to switch branches, each worktree gives you a fully independent working copy.

Autohand Code CLI builds on top of git worktrees with automation for common workflows: creating worktrees from templates, running commands across all worktrees, syncing with your main branch, and cleaning up when you are done.

## Quick start

Start a new Autohand session in an isolated worktree with a single flag:

``` bash
# Start a session in a new worktree (auto-generates a name)
autohand --worktree

# Start a session in a named worktree
autohand --worktree my-feature

# Start in a tmux session (automatically creates a worktree too)
autohand --tmux
```

When you use `--worktree`, Autohand creates a new branch and worktree directory, then runs the session inside it. Your main working directory stays untouched.

## Creating worktrees

### From the CLI flag

The simplest way to create a worktree is with the `--worktree` flag when starting Autohand:

``` bash
# New worktree with auto-generated name based on timestamp
autohand --worktree

# New worktree with a specific name
autohand --worktree auth-refactor
```

### Using templates

Autohand includes built-in templates that set up your worktree for specific workflows. Each template creates the worktree in a predictable location and can run setup commands like installing dependencies automatically.

| Template | Purpose | Setup |
|---|---|---|
| feature | Feature branch development | Installs dependencies automatically |
| hotfix | Hotfix from main/master | Installs dependencies automatically |
| release | Release branch preparation | Installs dependencies automatically |
| review | Pull request reviews | Minimal setup |
| experiment | Throwaway experiments | Creates detached worktree, no setup |

### Custom options

When creating worktrees programmatically or through the agent, you can specify:

-   **branch** - Check out an existing branch
-   **newBranch** - Create a new branch for the worktree
-   **baseBranch** - Branch to create the new branch from (defaults to current)
-   **detach** - Create a detached HEAD worktree for experiments
-   **template** - Use a named template for setup
-   **runSetup** - Run the template's setup commands after creation

## Parallel development

The main benefit of worktrees is working on multiple things at once. Here is a typical workflow:

``` bash
# Terminal 1: Working on the auth feature
autohand --worktree auth-feature
> "Add OAuth2 login flow to the auth service"

# Terminal 2: Fixing a bug on a separate branch
autohand --worktree fix-pagination
> "Fix the off-by-one error in the pagination component"

# Terminal 3: Reviewing a teammate's PR
autohand --worktree pr-review
> "Review the changes in PR #42 and leave feedback"
```

Each session runs in its own directory with its own branch. There are no conflicts between them, and your main working tree stays clean.

### Running commands across worktrees

Autohand can run commands across all your worktrees in parallel. This is useful for running tests, checking status, or building across all branches at once.

The parallel runner manages concurrency automatically and collects results from each worktree, reporting success, failure, output, and duration for each one.

## Syncing and rebasing

When your main branch moves forward, you need to keep feature worktrees up to date. Autohand handles this with two sync strategies:

-   **Rebase** (default) - Replays your branch commits on top of the latest main branch. Keeps a clean, linear history.
-   **Merge** - Creates a merge commit pulling in changes from main. Preserves the original branch history.

The sync operation fetches the latest changes and applies the chosen strategy to every active worktree. Worktrees with conflicts are flagged so you can resolve them manually.

## Status and monitoring

Autohand tracks detailed status for each worktree:

-   **Git changes** - Staged, modified, untracked, and conflicting files
-   **Ahead/behind** - How many commits ahead or behind the remote branch
-   **Last commit** - Hash, message, author, and date
-   **Health** - Whether the worktree is locked, prunable, or in a clean state

This gives you a dashboard view of all your active branches without having to `cd` into each one.

## PR review workflow

Autohand has a dedicated workflow for reviewing pull requests in isolated worktrees:

``` bash
# Create a worktree for reviewing a PR branch
autohand --worktree review-pr-42
```

The PR review workflow fetches the remote branch, creates a worktree for it, and sets everything up so you can review and test the changes without touching your current work. When you are done reviewing, you remove the worktree and the branch is cleaned up.

## Auto-mode isolation

Worktrees are central to how [auto-mode](/docs/working-with-autohand-code/yolo-mode.html) keeps your code safe. When Autohand runs autonomously, it:

1.  Creates an isolated branch named `autohand-automode-<timestamp>` with its own worktree
2.  Runs all file operations inside that worktree, never touching your main branch
3.  Creates checkpoint commits at regular intervals (configurable, default is every 5 iterations)
4.  Merges the worktree back into your main branch when the task completes successfully
5.  Preserves the worktree on failure or cancellation so you can inspect what happened

This means even if the agent makes a mistake during autonomous execution, your main branch is never affected. You can review the changes, cherry-pick what works, or discard the entire worktree.

## Cleanup

Over time, worktrees accumulate as you finish features and merge branches. Autohand provides cleanup automation that:

-   Finds worktrees whose branches have already been merged
-   Detects stale or prunable worktrees
-   Removes the worktree directory and optionally deletes the associated branch
-   Supports a force option for worktrees in a bad state

Locked worktrees are protected during cleanup to prevent accidentally removing work in progress.

## Tips

-   **Name your worktrees** - Use descriptive names like `auth-refactor` or `fix-nav-crash` instead of auto-generated ones. It makes status output much easier to scan.
-   **Use tmux for long tasks** - The `--tmux` flag creates both a worktree and a persistent tmux session, which is ideal for long-running autonomous tasks.
-   **Clean up regularly** - Merged worktrees take up disk space. Run cleanup after finishing a feature to keep things tidy.
-   **Check status before syncing** - Make sure worktrees have no uncommitted changes before syncing with the main branch to avoid conflicts.
-   **Use the review template for PRs** - It skips dependency installation since you are just reading code, making it much faster to set up.

## Frequently asked questions

### What are worktrees in Autohand?

Worktrees are isolated copies of your git repository that let you work on multiple features at the same time without switching branches. Autohand manages worktree creation, setup, and cleanup automatically. Each worktree gets its own directory and branch, keeping your main workspace clean.

### How do I start a worktree session?

Run autohand --worktree from the command line to create a new worktree for the session. Add a name with autohand --worktree feature-auth. Inside a session, the agent creates worktrees when using auto-mode or when you ask it to work in isolation.

### Does auto-mode use worktrees?

Yes. Auto-mode creates a git worktree by default so all changes happen on a separate branch. This keeps your main branch untouched until you are satisfied with the results. Disable worktree isolation with --no-worktree if you prefer changes on your current branch.