papagai Documentation — papagai 0.1.0 documentation

# papagai Documentation

`papagai` is a command-line tool that runs Claude AI on git repositories using isolated worktrees. It allows Claude to make changes in separate git worktrees, enabling multiple tasks to run simultaneously without interfering with the main working directory.

## Key Features

- Isolated Worktrees: All changes happen in dedicated git worktrees, keeping your main workspace clean

- Concurrent Tasks: Run multiple Claude tasks simultaneously without conflicts

- Automatic Git Integration: Changes are automatically committed and pulled back as branches

- Pre-written Tasks: Comes with built-in tasks and supports custom task templates

- Flexible Isolation: Supports both standard git worktrees and overlay filesystem worktrees

## Quick Start

### Installation

    $ pip install https://github.com/whot/papagai

If running from the git repository, use uv:

    $ uv run papagai

### Basic Usage

The primary commands are `code` and `do` to get Claude to perform tasks:

    $ papagai code
    Please tell me what you want me to do (Ctrl+D to complete)
    Update all .format() strings with f-strings
    Working in papagai/main-2025-11-12-7be3946e (based off main)
    [...]
    My work here is done. Check out branch papagai/main-2025-11-12-7be3946e

The `code` command includes programming best practices guidance, while `do` runs without the programming primer.

## Documentation Contents

User Guide

- Installation
  - Requirements
  - Installing from Source
  - Development Installation
  - Optional Dependencies
  - Verifying Installation
- Commands
  - papagai code
  - papagai do
  - papagai task
  - papagai review
  - papagai purge
  - Common Options
  - Frontmatter Options
- Tasks
  - Task Structure
  - Built-in Tasks
  - Custom User Tasks
  - Task Organization
  - Variable Substitution
  - Tool Restrictions
  - Best Practices
  - Example Task Library
- Concepts
  - Worktrees
  - Isolation Modes
  - Branch Naming
  - Workflow
  - Primers
  - Instruction Files
  - Git Integration
  - Security Considerations
  - Best Practices
  - Troubleshooting

Reference

- API Reference
  - CLI Module
  - Worktree Module
  - Markdown Module
  - Command Module

# Indices and tables

- Index

- Module Index

- Search Page