Skip to content

Quick start

This page takes about five minutes. At the end, Curupira watches one repository and hands every issue labelled agent-ready to Claude Code. Swap the agent or the label for your own.

You need Git, the GitHub CLI (gh), and one coding-agent CLI that is already signed in. Installation covers every platform and option.

1. Install and sign in

uv tool install curupira
gh auth login

pip install curupira
gh auth login

npm install -g @caipora-labs/curupira
gh auth login

The GitHub connector is a plugin that Curupira starts through uvx, so you also need uv on PATH. Nothing else is installed up front.

2. Write ~/.curupira/settings.toml

[repositories.api]
remote = "https://github.com/acme/api.git"   # (1)!

[agents.defaults]
profile = "claude"
timezone = "UTC"

[agents.profiles.claude]
provider = "claude"                           # (2)!

[plugins.plugins-py]                          # (3)!
type = "uvx"
args = ["--from", "curupira-plugins", "curupira-plugins"]

[automations.resolve-ready-issues]
trigger_type = "plugins-py/github-issues"     # (4)!
repository = "api"
repo = "acme/api"
labels = ["agent-ready"]
prompt = """
Resolve issue #${issue_number}: ${issue_title}

${issue_body}
"""
  1. Where the agent works. Curupira clones it once and gives each task its own worktree.
  2. Any supported agent: codex, gemini, opencode, and more.
  3. Registers the GitHub connector under the alias plugins-py. Other connectors are registered the same way.
  4. <alias>/<trigger>: the issues trigger from the connector registered above. repo and labels are its filters, and ${issue_number} and the other fields fill the prompt.

3. Check it, preview it, run it

curupira validate      # is the file correct?
curupira run --dry-run # which task would run, and the exact prompt the agent gets
curupira run --watch   # keep polling and run tasks as they appear

Safe to repeat

--dry-run clones nothing and starts no agent. Use it while you tune filters and the prompt.

Next steps