Git Worktree Architecture

Sidequest uses git worktrees to let you run multiple agent sessions against the same repository in parallel — each on its own branch, with its own working directory, without any stashing or switching.

What Are Git Worktrees?

A git worktree is a linked copy of your repository that shares the same .git object store but has its own working tree and checked-out branch. Unlike cloning, worktrees share history, refs, and objects with the original repo. This means they are created instantly and use almost no extra disk space for history — only the checked-out files.

# Standard git: one repo, one branch at a time
~/my-project (main)

# With worktrees: one repo, multiple branches simultaneously
~/my-project (main)                                    # your original repo
~/.sidequest/worktrees/<quest-id> (feat/orders-rate-limit)  # worktree for quest A
~/.sidequest/worktrees/<quest-id> (fix/checkout-flake)      # worktree for quest B

Why Sidequest Uses Worktrees

Without worktrees, running parallel branches requires either cloning the repo multiple times (slow, wastes disk) or constantly stashing and switching branches (error-prone, blocks other work). Worktrees solve both problems:

• True isolation. Each quest gets its own directory. Agent sessions cannot interfere with each other.
• No stashing. Your main branch stays untouched. Uncommitted work in one quest does not affect another.
• Shared git history. All worktrees share the same object database. Fetches and commits in one are visible from another.
• Fast creation. Creating a worktree takes milliseconds since it only needs to check out files, not copy the entire repo.

Directory Structure

All worktrees live under a centralized directory in your home folder:

~/.sidequest/
  worktrees/
    4df63f83-4094-4d16-9517-3d514b405e5b/   # Worktree or Review quest
    7a2c9e10-....../
  multirepo/
    9b1d.../                                # multi-repo quest
      frontend/                             # one worktree per child repo
      backend/

The quest id is the directory name, so Sidequest can map a working directory back to its quest — this is how the Claude Code Stop hook knows which quest needs attention.

Lifecycle of a Worktree quest

graph TD
A[Activate quest] --> B["git worktree add -b quest/<id8> ~/.sidequest/worktrees/<id> <base>"]
B --> C[Set upstream to base branch]
C --> D{Setup command?}
D -->|yes| E[Run it in the worktree]
D -->|no| F
E --> F[Launch agent session]
F --> G[Rename branch to agent-suggested name]
H[Complete quest] --> I[Interrupt agent, keep worktree]
I -->|retention expires| J["git worktree remove"]

1. Branch creation. The worktree is created from the base branch you chose, on a temporary branch named quest/ plus the first eight characters of the quest id.
2. Upstream. Sidequest sets branch.<name>.remote and branch.<name>.merge to the base branch so gh pr create and git push target the right place.
3. Setup command. If the project defines one, it runs in the new worktree through your login shell before the agent starts (only when the worktree is newly created).
4. Naming. In the background, Sidequest asks Claude for a branch name derived from your prompt (for example feat/orders-rate-limit) and renames the branch. If no usable name comes back, the temporary name stays.
5. Completion. Completing the quest interrupts the agent and keeps the worktree for the Quest Retention window so the quest can be restored. When retention expires — or immediately, if retention is disabled — the worktree is removed with git worktree remove --force, falling back to deleting the directory and git worktree prune. The branch is never deleted by Sidequest.

Review quests

Review quests fetch the pull request’s head branch (git fetch origin +head:head) and add a worktree on it. If that branch is already checked out in another worktree — for example your own — git would refuse, so Sidequest fetches into refs/remotes/origin/<head> instead and adds the worktree detached at that commit. Your checkout is never touched.

Multi-repo quests

For legacy multi-repo projects, Sidequest creates one worktree per child repository under ~/.sidequest/multirepo/<quest-id>/, all on the same branch name, and runs the agent in the parent directory. See Multi-Project Workflows.

Diff stats and the Changes panel

Each quest card shows +added −removed for its branch relative to the base branch, refreshed in batches for all active quests. The Changes panel reads the worktree directly, so uncommitted edits appear immediately.

Disk usage

Worktrees contain a full checkout plus whatever the agent builds there (node_modules, target, …), so they can be large. Settings > Storage > Worktree Storage shows the total, lists worktrees that are orphaned or belong to completed quests, and reclaims them. Reclaiming a completed quest’s worktree keeps its branch and commits.

If Sidequest was force-quit and a directory is left behind without a quest, it appears there as Orphaned. From the shell:

ls ~/.sidequest/worktrees/
rm -rf ~/.sidequest/worktrees/<quest-id>
cd ~/your-repo && git worktree prune

Working with quest branches yourself

Everything Sidequest does is ordinary git:

git worktree list                 # shows every quest worktree and its branch
git branch -a                     # quest branches appear here
git log main..feat/orders-rate-limit

You can push a quest branch, open a PR, rebase it, or merge it from any tool. Sidequest does not merge or delete branches on its own; ask the agent to run gh pr create, or do it yourself.