API Reference — papagai 0.1.0 documentation

# API Reference

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

## CLI Module

class papagai.cli.Context(dry_run: bool = False)

  Bases: `object`

  dry_run: bool = False
  __init__(dry_run: bool = False) → None

class papagai.cli.Isolation(*values)

  Bases: `StrEnum`

  AUTO = 'auto'
  WORKTREE = 'worktree'
  OVERLAYFS = 'overlayfs'

papagai.cli.get_builtin_tasks_dir() → Path

papagai.cli.get_builtin_primers_dir() → Path

papagai.cli.get_xdg_task_dir() → Path

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

  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

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

papagai.cli.merge_into_target_branch(repo_dir: Path, dest: str, src: str) → int

papagai.cli.purge_branches(repo_dir: Path) → None

  Delete all papagai branches from the repository.

papagai.cli.purge_worktrees(repo_dir: Path) → None

  Remove any leftover git worktrees created by papagai.

papagai.cli.purge_overlays(repo_dir: Path) → None

  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

  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

papagai.cli.list_all_tasks() → int

  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

  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)

  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

    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)

  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
  classmethod is_supported() → bool

    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

    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 = '')

  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

    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

    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>)

  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

    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

    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

    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]

  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