Commands — papagai 0.1.0 documentation

# Commands

This page describes all available papagai commands.

## papagai code

Run Claude with a programming primer that provides best practices guidance.

    $ papagai code [OPTIONS] [INSTRUCTIONS_FILE]

Options:

- `--branch, -b BRANCH`: Base branch to work from (default: current branch)

- `--keep/--no-keep`: Keep or remove the worktree after completion (default: remove)

- `--isolation CHOICE`: Isolation mode - `auto`, `worktree`, or `overlayfs` (default: auto)

- `--dry-run`: Show what would be done without executing

Arguments:

- `INSTRUCTIONS_FILE`: Optional path to a markdown file with instructions. If not provided, will prompt for input.

Description:

The `code` command includes a programming primer that instructs Claude on:

- Code quality principles

- Git best practices

- Development workflow

- Testing and documentation standards

This primer is automatically prepended to your instructions, allowing you to focus on the specific task.

Examples:

Interactive mode (prompts for instructions):

    $ papagai code
    Please tell me what you want me to do (Ctrl+D to complete)
    Update all .format() strings with f-strings

From a file:

    $ echo "Update all .format() strings with f-strings" > task.md
    $ papagai code task.md

With options:

    $ papagai code --branch main --keep task.md

## papagai do

Run Claude without the programming primer for more general tasks.

    $ papagai do [OPTIONS] [INSTRUCTIONS_FILE]

Options:

Same as `papagai code`.

Description:

The `do` command works exactly like `code` but does not include the programming primer. Use this when you want full control over the instructions or for non-programming tasks.

Example:

    $ echo "You are a native Spanish speaker. Translate all strings to Spanish" > translate.md
    $ papagai do translate.md

## papagai task

Run pre-written tasks from built-in or custom task libraries.

    $ papagai task [OPTIONS] [TASK_NAME]

Options:

- `--list`: List all available tasks

- `--branch, -b BRANCH`: Base branch to work from

- `--keep/--no-keep`: Keep or remove the worktree after completion

- `--isolation CHOICE`: Isolation mode

Arguments:

- `TASK_NAME`: Name of the task to run (e.g., `python/update-to-3.9`)

Description:

Tasks are markdown files with frontmatter stored in:

- Built-in tasks: Shipped with papagai in `papagai/tasks/**/*.md`

- User tasks: `$XDG_CONFIG_HOME/papagai/tasks/**/*.md`

Task files must have a `description` key in the frontmatter:

    ---
    description: Update a Python code base to Python 3.9+
    ---
    You are a very smart LLM. Please update this codebase...

Variable Substitution:

Tasks support variable substitution:

- `{BRANCH}` - Original branch name

- `{WORKTREE_BRANCH}` - Current worktree branch name

Examples:

List available tasks:

    $ papagai task --list
    Built-in tasks:
      python/update-to-3.9  ... Update a Python code base to Python 3.9+
      c/modernize           ... Modernize C code to C11 standards

    User tasks:
      myproject/refactor    ... Refactor myproject code

Run a task:

    $ papagai task python/update-to-3.9

## papagai review

Convenience command for code review.

    $ papagai review [OPTIONS]

Options:

Same as `papagai code`.

Description:

This command reviews all commits on the current branch, providing inline feedback and creating fixup commits for any issues found. It’s a shortcut for running a code review task.

Example:

    $ papagai review

## papagai purge

Clean up papagai branches.

    $ papagai purge [OPTIONS]

Options:

- `--dry-run`: Show what would be deleted without actually deleting

Description:

Removes all branches matching the `papagai/*` pattern. Use this to clean up branches created by papagai after you’ve merged or reviewed the changes.

Example:

    $ papagai purge
    Deleting branch papagai/main-20251112-1030-7be3946e
    Deleting branch papagai/main-20251113-1445-abc123fe

## Common Options

These options are available for most commands:

### Isolation Modes

The `--isolation` option controls how worktrees are isolated:

- `auto` (default): Automatically choose based on availability (prefers overlayfs if available)

- `worktree`: Use standard git worktrees

- `overlayfs`: Use fuse-overlayfs for copy-on-write isolation (requires fuse-overlayfs)

### Branch Selection

The `--branch` or `-b` option specifies which branch to base the work on:

    $ papagai code --branch develop task.md

### Worktree Retention

By default, worktrees are removed after the task completes. Use `--keep` to retain them:

    $ papagai code --keep task.md

## Frontmatter Options

Instruction files can include YAML frontmatter to control behavior:

### Tool Restrictions

Limit which tools Claude can use:

    ---
    tools: Bash(uv :*)
    ---
    Update all dependencies using uv

This restricts Claude to only use the `uv` command via Bash.