Rookery

✨ Why Rookery

Most coding agents either chat with you in an editor or open a PR you didn't ask for. Rookery sits where your team already works — GitHub issues — and keeps a human on every gate that matters.

⚙️ How it works

flowchart LR
  L([🏷️ label]) --> P[📝 plan]
  P -- question --> Q{{💬 you reply}}
  Q --> P
  P --> A{{✅ approve}}
  A --> T[🧱 task 1 … N<br/>one commit each]
  T --> C[🔍 checks + review]
  C --> PR([📬 draft PR])

The plan, the task list and a decisions.md log ship with the PR, so reviewers see why, not only what. Follow the issue's rookery:* label to see where it is:

Label	Meaning
rookery:planning	writing the plan
rookery:awaiting-input	a question is in the comments — answer it
rookery:awaiting-approval	read the plan, then comment approve / lgtm / go ahead
rookery:implementing	working through the task list
rookery:reviewing	the reviewer is reading the finished diff
rookery:done	the draft PR is open and the review is clean
rookery:changes-wanted	the draft PR is open; the reviewer or a check wants changes
rookery:error	the reason is the last comment; fix it, then approve resumes

💬 Follow-ups and PR reviews

• On the issue, once its PR is open: mention @rookery-agent with a note — "rename the flag", "why this index?" — and it updates the PR or answers the question.
• On any open PR: mention @rookery-agent (or add the rookery:pr-review label, or request a review from it) for one advisory review: a verdict, a findings table and details. Steer it with a note — @rookery-agent check the migration.

🚀 Get started

Hosted — two minutes

1. Open rookery.run and sign in with GitHub.
2. Install the App on a repo and add your model key.
3. Label an issue rookery:trigger.

Full guide: docs/getting-started.md.

Local CLI

The same flow on your own machine, against a local git repo: no GitHub App, no webhook, no account. Rookery plans in its own worktree, waits for your approve, then runs each task in a fresh Claude session and commits it. Nothing is pushed.

You need git and the claude CLI (logged in, or an API key through rookery config). Install the rookery binary:

# Windows
powershell -ExecutionPolicy Bypass -c "irm https://github.com/sa-es-ir/rookery/releases/latest/download/rookery-cli-installer.ps1 | iex"

# macOS / Linux
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/sa-es-ir/rookery/releases/latest/download/rookery-cli-installer.sh | sh
# or, with a Rust toolchain
cargo install rookery-cli --locked

cd ~/code/my-repo
rookery doctor                     # checks git, claude and the repo (one ~$0.01 call)
rookery new "add a --json flag"    # plan; it asks, or shows the tasks
rookery reply 1 "use serde"        # answer its questions
rookery approve 1                  # run the tasks, the after steps and the review
rookery ask 1 "rename the flag"    # a question gets an answer; a change is committed and reviewed
rookery review                     # advisory review of the current branch

Run rookery alone for an interactive prompt. ls, show, log, drop and memory manage items, runs and repo notes; Ctrl-C stops a run and keeps what is committed. Full guide: docs/cli.md.

Self-host

You need Python 3.10+, git, openssl, the gh CLI and the claude CLI on your PATH, plus your own GitHub App. No packages to install.

git clone https://github.com/sa-es-ir/rookery && cd rookery
cp .env.example .env               # WEBHOOK_SECRET, APP_ID, APP_KEY, ...
python agent.py owner/repo 12      # dry run: plan issue 12, no webhook needed
python agent.py                    # webhook + portal on http://127.0.0.1:8787

For local development, forward the App's webhook with npx smee-client --url https://smee.io/<channel> --target http://127.0.0.1:8787/. For a real server, follow docs/self-hosting.md and the full Linux guide in DEPLOY.md.

🔑 Model providers

The agent harness is always the Claude Code CLI, so every safety rule holds whichever model is behind it. The model is chosen per GitHub owner: an owner's own key, or the operator's default.

Provider	Status	Models behind the agent
Claude (CLI login)	✅ Supported	Opus plans and reviews, Sonnet builds
Anthropic API key	✅ Supported	Same Claude models, billed to your key
DeepSeek	✅ Supported	DeepSeek V4 Pro / Flash
Z.ai (GLM)	✅ Supported	GLM 5.3 / GLM 5.3 Flash
OpenRouter	🧪 Next	GPT and Gemini models, after quality tests
Claude on Bedrock	📋 Planned	Claude through your own AWS account
Codex CLI	🔭 Later	OpenAI models in their native harness

Owners add keys on the portal's Keys page. Keys are encrypted at rest, never shown again (only the last 4 characters), and the daily caps still apply. More: docs/keys.md.

This is the beginning of the README. Read the rest at the original. Read the full README ↗