> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dotbot.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Per-task git worktree isolation

> Learn how dotbot gives every task its own git branch and worktree so multiple AI agents can write code simultaneously without file conflicts.

When multiple AI tasks run at the same time, they must not write to the same files simultaneously. dotbot solves this by giving every task its own git branch and its own git worktree — a full checkout of the repository in a separate directory on disk. Each task operates in complete isolation, with its own working tree, its own staged changes, and its own commit history. The task queue and control directory are linked in via directory junctions (Windows) or symlinks (macOS/Linux), so every task sees the same live queue state without duplicating data between worktrees.

## How it works

### Branch and worktree creation

When a task enters the `in-progress` state, dotbot automatically creates a dedicated git branch and worktree for it before the provider session starts:

1. Derives a **branch name** from the task's short ID and a URL-safe slug of the task name:

   ```
   task/{short-id}-{slug}
   ```

   For example: `task/a1b2c3d4-add-user-authentication`

2. Creates a **worktree path** under a `worktrees/` directory next to the repo root:

   ```
   ../worktrees/{repo-name}/task-{short-id}-{slug}/
   ```

   For example: `../worktrees/my-app/task-a1b2c3d4-add-user-authentication/`

3. Runs `git worktree add -b <branch> <path> <base-branch>` to create the branch and check it out in the new worktree directory.

4. Links the central task queue and control directory into the worktree via directory junctions or symlinks, so the task process reads and writes the same live queue and runtime state as every other task. The framework itself — the MCP server, runtime, prompts, and hooks — is resolved separately from the active install through `$env:DOTBOT_HOME` and is not copied into the worktree.

### Task execution in isolation

The AI agent runs entirely within the worktree directory. It reads project files, edits code, and stages commits — all within that isolated tree. It cannot accidentally modify another task's files because those files are in a different worktree on a different branch. The linked task queue and control directory let the agent communicate with the rest of the system, updating task state without copying data between worktrees. Product artifacts are branch-local: each worktree has its own copy that is committed on the task branch and merged when the task completes.

### Completion and cleanup

When a task reaches `done`, dotbot automatically cleans up the worktree:

1. Removes the directory junctions so git sees only the task's own tracked files
2. Rebases the task branch onto the current base branch (brings it up to date)
3. Squash-merges the task branch into main — producing a single, clean commit
4. Tags the merge commit with the task short ID: `feat: <task name> [task:XXXXXXXX]`
5. Deletes the task branch with `git branch -D`
6. Removes the worktree with `git worktree remove`
7. Removes the entry from the worktree map in `.bot/.control/`

<Note>
  dotbot uses squash merges so every completed task produces exactly one commit on main, regardless of how many intermediate commits the AI made during implementation.
</Note>

## Example paths

Given a repository named `my-app` cloned at `~/projects/my-app`, a task with short ID `a1b2c3d4` and name "Add user authentication" produces:

| Item             | Path                                                                 |
| ---------------- | -------------------------------------------------------------------- |
| Branch           | `task/a1b2c3d4-add-user-authentication`                              |
| Worktree         | `~/projects/worktrees/my-app/task-a1b2c3d4-add-user-authentication/` |
| Merge commit tag | `feat: Add user authentication [task:a1b2c3d4]`                      |

A second concurrent task with short ID `e5f6a7b8` and name "Fix login bug" runs simultaneously at:

| Item     | Path                                                       |
| -------- | ---------------------------------------------------------- |
| Branch   | `task/e5f6a7b8-fix-login-bug`                              |
| Worktree | `~/projects/worktrees/my-app/task-e5f6a7b8-fix-login-bug/` |

Both tasks work in complete isolation with no risk of conflicting edits.

## Benefits

### Concurrent tasks without conflicts

Because each task has its own working tree, multiple tasks can edit different parts of the codebase at the same time. dotbot's multi-slot execution model takes full advantage of this — you can run several task-runners in parallel, shortening wall-clock time for large task queues.

### Clean git history

Squash merges produce one logical commit per task on the main branch. The commit message includes the task name and short ID, so the history is readable and every change is traceable back to the task that produced it. To find all commits from a specific task, search git history for its ID tag:

```
feat: Add user authentication [task:a1b2c3d4]
```

### Easy rollback

The task branch exists on disk from the moment the task goes `in-progress` until the squash merge completes. If something goes wrong during implementation, you can inspect the branch, cherry-pick commits, or simply delete the branch and reset the task to `todo` to try again.

<Warning>
  If a process crashes before the worktree is cleaned up, the branch and worktree directory remain on disk. Run `dotbot doctor` to detect orphaned worktrees and clean them up safely.
</Warning>

## Shared state and framework resolution

A task worktree does not carry a full copy of the framework. dotbot keeps three things separate: the live runtime state that every task shares, the branch-local artifacts each task owns, and the framework that is resolved from the active install.

| Path                                          | How the worktree gets it                                                                                           |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `.bot/.control/`                              | Linked to the project's central control directory — process registry, worktree map, settings, and the activity log |
| `.bot/workspace/tasks/`                       | Linked to the project's central task queue (todo, in-progress, done, and the other status directories)             |
| `.bot/workspace/product/`                     | Branch-local — the worktree has its own copy, committed on the task branch                                         |
| `.bot/content/<type>/<name>/`                 | Project-level workflow and stack overrides, materialised in the repository and carried by the checkout             |
| Framework runtime, MCP server, prompts, hooks | Resolved at runtime from the active install via `$env:DOTBOT_HOME`; never copied into the project                  |

Because the control directory and task queue are linked rather than copied, the MCP tools in every worktree process read from and write to the same live state. Task state transitions, question routing, and session tracking stay consistent even when many tasks run concurrently. The framework is shared a different way: each process resolves it from `$env:DOTBOT_HOME`, so updating the install updates every project at once.

## Relationship to multi-slot execution

Per-task worktree isolation is what makes [multi-slot concurrent execution](/concepts/execution-engine#multi-slot-concurrent-execution) safe. Without isolation, two AI agents writing to the same working tree at the same time would produce merge conflicts, corrupt staged changes, or cause non-deterministic test results. With isolation, each slot operates independently and the only shared state is the task queue and control directory — both accessed through the directory links under controlled conditions.