Commands
This page describes all available papagai commands. The options listed for
each command are the ones users are likely to user. Use the --help output
to see all options.
Any work by papagai will end up in a papagai/<branchname>-<date-time>-<uuid>
branch and the papagai/latest branch will be updated to point to that branch.
papagai code
Run Claude with a programming primer that provides best practices guidance. This primer is automatically prepended to your instructions, allowing you to focus on the specific task.
$ papagai code [OPTIONS] [INSTRUCTIONS_FILE]
Options:
--branch, -b BRANCH: Branch to merge work into (.means current branch)--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.
Note
Note that the primer is a relatively generic set of instructions. For complex
tasks it may be better to use the task command and custom primers.
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
If you are confident in Claude’s ability to write code you can ask papagai
to merge the results directly into a local branch. If the branch does not
exist yet it will be created.
$ papagai code --branch newfeature implement-my-new-feature.md
Instruction files can include YAML frontmatter to control behavior. For example: to add to the tools Claude can use:
---
tools: Bash(uv :*)
---
Update all dependencies using uv
This adds the uv command via Bash to the tools Claude may use.
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
Arguments:
TASK_NAME: Name of the task to run (e.g.,python/update-to-3.9)
Description:
Tasks are markdown files. Some built-in tasks are shipped with papagai
but you may add your own custom tasks as
$XDG_CONFIG_HOME/papagai/tasks/**/*.md.
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
Task Structure
Tasks are markdown files with YAML frontmatter:
---
description: A short description of what this task does
tools: Bash(git:*), Read, Write, Edit # Optional: tool restrictions
---
# Task Instructions
You are an expert programmer. Please analyze this codebase and...
The description field is required and is shown in the task list.
Variable Substitution:
Tasks support variable substitution:
{BRANCH}- Original branch name{WORKTREE_BRANCH}- Current worktree branch name
papagai review
Run Claude with a primer that provides best practices guidance for code reviews.
$ papagai review [OPTIONS]
Options:
--branch, -b BRANCH: Branch to merge work into (.means current branch)--dry-run: Show what would be done without executing--mr MR_ID: Merge request ID to review (e.g.,--mr 1234)
Description:
This command reviews all commits on the current branch, providing inline
feedback and creating fixup commits for any issues found on the papagai
branch.
The --mr option allows you to review a merge request directly by its ID.
This requires your repository to be configured to fetch merge requests. To
enable this, add the merge request fetch configuration:
$ git config --add remote.origin.fetch "+refs/merge-requests/*/head:refs/remotes/origin/mr/*"
This maps GitLab merge requests to local refs like origin/mr/1234. The
--mr option cannot be used together with the --ref option.
Examples:
Review the current branch:
$ papagai review
Review a specific merge request:
$ papagai review --mr 1234
papagai purge
Clean up papagai branches.
$ papagai purge [OPTIONS]
Options:
--no-branches: Do not delete anypapagaigit branches--no-overlays: Do not unmount any overlays--no-worktrees: Do not delete any git worktrees--dry-run: Show what would be deleted without actually deleting
Description:
Removes all papagai branches, git worktrees and overlays. 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