API Reference

This page provides API documentation for papagai’s Python modules.

CLI Module

class papagai.cli.Context(dry_run: bool = False)[source]

Bases: object

dry_run: bool = False

__init__(dry_run: bool = False) → None

class papagai.cli.Isolation(*values)[source]

Bases: StrEnum

AUTO = 'auto'

WORKTREE = 'worktree'

OVERLAYFS = 'overlayfs'

papagai.cli.get_builtin_tasks_dir() → Path[source]

papagai.cli.get_builtin_primers_dir() → Path[source]

papagai.cli.get_xdg_task_dir() → Path[source]

papagai.cli.get_branch(repo_dir: Path, ref: str = 'HEAD') → str[source]

Get the branch name for a given ref (commit-ish).

Parameters:

repo_dir – Path to git repository
ref – Git ref (branch name, HEAD, etc.). Default: HEAD

Returns:

The branch name

Raises:

subprocess.CalledProcessError if ref doesn't exist or not a git repo –

papagai.cli.branch_exists(repo_dir: Path, branch: str) → bool[source]

papagai.cli.create_branch_if_not_exists(repo_dir: Path, branch_spec: str | None, base_branch: str) → str[source]

papagai.cli.merge_into_target_branch(repo_dir: Path, dest: str, src: str) → int[source]

papagai.cli.purge_branches(repo_dir: Path) → None[source]: Delete all papagai branches from the repository.

papagai.cli.purge_worktrees(repo_dir: Path) → None[source]: Remove any leftover git worktrees created by papagai.

papagai.cli.purge_overlays(repo_dir: Path) → None[source]: Remove and unmount any leftover overlayfs created by papagai.

papagai.cli.run_claude(worktree_dir: Path, instructions: str, dry_run: bool, allowed_tools: list[str] | None = None) → None[source]: Run the Claude review agent.

papagai.cli.claude_run(base_branch: str, instructions: MarkdownInstructions, dry_run: bool, branch_prefix: str = '', isolation: Isolation = Isolation.AUTO, keep: bool = False, target_branch: str | None = None) → int[source]

papagai.cli.list_all_tasks() → int[source]

List all available tasks from the instructions directory.

Returns:: Exit code (0 for success, 1 for error)

Worktree Module

Git worktree management for papagai.

papagai.worktree.repoint_latest_branch(repo_dir: Path, branch: str) → None[source]

Update the papagai/latest branch to point to the specified branch.

Removes the papagai/latest branch if it exists, then creates it pointing to the same commit as the specified branch.

Parameters:

repo_dir – Path to the repository root
branch – Branch name to point papagai/latest to

class papagai.worktree.Worktree(worktree_dir: Path, branch: str, repo_dir: Path, keep: bool = False)[source]

Bases: object

Git worktree context manager for automated branch creation and cleanup.

worktree_dir

Path to the worktree directory

Type:: pathlib.Path

branch

Name of the created branch

Type:: str

repo_dir

Path to the repository root

Type:: pathlib.Path

keep

If True, skip worktree directory removal during cleanup

Type:: bool

worktree_dir: Path

branch: str

repo_dir: Path

keep: bool = False

classmethod from_branch(repo_dir: Path, base_branch: str, branch_prefix: str | None = None, keep: bool = False) → Self[source]

Create a new review branch using git worktree.

Parameters:

repo_dir – Path to the repository root
base_branch – Branch to base the new branch on
branch_prefix – Optional prefix for the branch name
keep – If True, skip worktree directory removal during cleanup

Returns:

Worktree instance

Raises:

subprocess.CalledProcessError – If git worktree creation fails

__init__(worktree_dir: Path, branch: str, repo_dir: Path, keep: bool = False) → None

class papagai.worktree.WorktreeOverlayFs(worktree_dir: Path, branch: str, repo_dir: Path, keep: bool = False, overlay_base_dir: Path | None = None, mount_dir: Path | None = None)[source]

Bases: Worktree

Git worktree using overlay filesystem (fuse-overlayfs).

This class creates a copy-on-write worktree using fuse-overlayfs, where the original repository is the read-only lower layer and modifications are stored in an upper layer.

worktree_dir

Path to the mounted overlay directory

Type:: pathlib.Path

branch

Name of the created branch

Type:: str

repo_dir

Path to the repository root

Type:: pathlib.Path

keep

If True, skip unmounting and directory removal during cleanup

Type:: bool

overlay_base_dir

Path to the overlay filesystem base directory

Type:: pathlib.Path | None

mount_dir

Path to the mounted overlay filesystem

Type:: pathlib.Path | None

overlay_base_dir: Path | None = None

mount_dir: Path | None = None

umount(check: bool = False) → None[source]

classmethod is_supported() → bool[source]

Check if fuse-overlayfs is available on the system.

Returns:: True if fuse-overlayfs command is available, False otherwise

classmethod from_branch(repo_dir: Path, base_branch: str, branch_prefix: str | None = None, keep: bool = False) → Self[source]

Create a new overlay worktree using fuse-overlayfs.

Directory structure: - $XDG_CACHE_HOME/papagai/<project>/<branch>-<date>-<uuid>/

upperdir/

workdir/ - fuse-overlayfs workdir

mounted/ - mount point

The repo_dir is the read-only lower layer with fuse-overlayfs.

Parameters:

repo_dir – Path to the repository root
base_branch – Branch to base the new branch on
branch_prefix – Optional prefix for the branch name
keep – If True, skip unmounting and directory removal during cleanup

Returns:

WorktreeOverlayFs instance with mounted overlay filesystem

Raises:

subprocess.CalledProcessError – If git or mount operations fail
RuntimeError – If fuse-overlayfs is not available

__init__(worktree_dir: Path, branch: str, repo_dir: Path, keep: bool = False, overlay_base_dir: Path | None = None, mount_dir: Path | None = None) → None

Markdown Module

Markdown file parsing utilities.

class papagai.markdown.Markdown(frontmatter: dict[str, str] = <factory>, text: str = '')[source]

Bases: object

Markdown file with parsed frontmatter.

frontmatter

Dictionary of frontmatter key-value pairs

Type:: dict[str, str]

frontmatter: dict[str, str]

text: str = ''

classmethod from_string(content: str) → Self[source]

Parse a markdown string and extract frontmatter.

Frontmatter is delimited by — at the start and end, and contains key: value pairs that may span multiple lines.

Parameters:: content – Markdown content as a string
Returns:: Markdown instance with parsed frontmatter

classmethod from_file(file_path: Path) → Self[source]

Parse a markdown file and extract frontmatter.

Frontmatter is delimited by — at the start and end, and contains key: value pairs that may span multiple lines.

Parameters:

file_path – Path to the markdown file

Returns:

Markdown instance with parsed frontmatter

Raises:

FileNotFoundError – If the file does not exist
PermissionError – If the file cannot be read

__init__(frontmatter: dict[str, str] = <factory>, text: str = '') → None

class papagai.markdown.MarkdownInstructions(frontmatter: dict[str, str] = <factory>, text: str = '', description: str = '', tools: list[str] = <factory>)[source]

Bases: Markdown

Markdown file with parsed instructions frontmatter.

Inherits from Markdown and adds convenience fields for description and tools.

description

Description from frontmatter, or empty string if not found

Type:: str

tools

List of tool strings parsed from frontmatter, or empty list if not found

Type:: list[str]

description: str = ''

tools: list[str]

classmethod from_string(content: str) → Self[source]

Parse a markdown string and extract instructions frontmatter.

Parses the description and tools from the frontmatter. Tools are comma-separated, but commas inside parentheses/braces are preserved.

Parameters:: content – Markdown content as a string
Returns:: MarkdownInstructions instance with parsed frontmatter and fields

classmethod from_file(file_path: Path) → Self[source]

Parse a markdown file and extract instructions frontmatter.

Parses the description and tools from the frontmatter. Tools are comma-separated, but commas inside parentheses/braces are preserved.

Parameters:

file_path – Path to the markdown file

Returns:

MarkdownInstructions instance with parsed frontmatter and fields

Raises:

FileNotFoundError – If the file does not exist
PermissionError – If the file cannot be read

combine(other: Self) → Self[source]

Combine this MarkdownInstructions with another.

Creates a new MarkdownInstructions with: - Text from both objects concatenated (self.text + other.text) - Tools from both objects combined (deduplicated) - Description from only the first object (self) - Frontmatter merged from both objects

Parameters:: other – Another MarkdownInstructions to combine with
Returns:: New MarkdownInstructions with combined content

__init__(frontmatter: dict[str, str] = <factory>, text: str = '', description: str = '', tools: list[str] = <factory>) → None

Command Module

Command execution utilities.

papagai.cmd.run_command(cmd: list[str], cwd: Path | None = None, check: bool = True) → CompletedProcess[str][source]

Run a command and return the result.

Parameters:

cmd – Command and arguments as a list of strings
cwd – Optional working directory for the command
check – If True, raise CalledProcessError on non-zero exit

Returns:

CompletedProcess instance with stdout, stderr, and return code

Raises:

subprocess.CalledProcessError – If check is True and command fails