Concepts — papagai 0.2.0 documentation

# 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