Concepts

This page explains the core concepts and architecture of papagai.

Worktrees

What are Worktrees?

Worktrees allow you to have multiple working directories for a single repository. Papagai uses worktrees to isolate Claude’s work from your main development environment.

Benefits:

  • Work on multiple tasks simultaneously without switching branches

  • Keep your main workspace clean and unaffected by Claude’s changes

  • Easy rollback - just delete the worktree branch if you don’t like the changes

  • Safe experimentation without risking your working code

Isolation Modes

Papagai supports two isolation modes for running Claude: OverlayFS and git worktrees. The default is to use OverlayFS if the fuse-overlayfs binary is found, otherwise normal git worktrees are used. See the --isolation option on the various papagai commands.

We prefer OverlayFS because it separates he main git repo and protects it from Claude potentially messing with other branches on the repository. Only the papagai branch is pulled back into the main repo, so were Claude to maliciously modify the main branch those changes will be thrown away at the end of the task. git worktrees cannot provide this protection.

How Papagai Uses Worktrees

When you run a papagai command:

  1. Creates a new git worktree in a temporary directory

    • for OverlayFS this is in XDG_CACHE_HOME/papagai/<reponame>/<base-branch>`

    • for git worktree this is in $PWD/papagai/<base-branch>/`

  2. Creates a new branch with the naming pattern: papagai/<prefix><base>-<date-time>-<uuid>

  3. Runs Claude in that isolated worktree

  4. Commits changes to the worktree branch

  5. Returns to your original workspace

    • for OverlayFS: pull the work branch back into the main repo

  6. Removes the worktree directory (see the --keep option if you need to keep the tree)

The papagai/latest branch always points to the most recent work, making it easy to find.

Branch Naming

Branch Naming Convention

Papagai creates branches following a specific pattern:

papagai/<prefix><base-branch>-<YYYYmmdd-HHMM>-<uuid>

Components:

  • papagai/ - Namespace prefix for easy identification

  • <prefix> - Optional prefix (e.g., review/ for papagai review)

  • <base-branch> - The branch you were on when starting

  • <YYYYmmdd-HHMM> - Timestamp when the branch was created

  • <uuid> - Short unique identifier

Examples:

papagai/main-20251112-1030-7be3946e
papagai/wip/develop-20251113-1445-abc123fe

The special branch papagai/latest always points to the most recently completed papagai task. This makes it easy to find your latest work without remembering the exact branch name.

Finding Your Work

List all papagai branches:

$ git branch --list 'papagai/*'
papagai/latest
papagai/main-20251112-1030-7be3946e
papagai/main-20251113-1445-abc123fe

Check out the latest work:

$ git checkout papagai/latest