# Overview Rookery is a GitHub App. It turns a GitHub issue into a draft pull request. You add one label to an issue. Rookery reads the issue and writes a plan. You approve the plan with a comment. Rookery then does the tasks in the plan, one at a time, and opens a draft pull request. Rookery never merges. A human reviews and merges the pull request. ## The loop 1. You add the `rookery:trigger` label to an issue. 2. Rookery writes a plan and a task list. If it needs information, it asks a question in a comment. 3. You answer the questions. Then you comment `approve`. 4. Rookery does each task in a new Claude session and commits each task. 5. A reviewer agent reads the full change. 6. Rookery pushes the branch and opens a draft pull request. ```flow loop ``` The diagram plays the loop. Select a step to stop it and see what the step does. ## What you get - A branch `feature/issue-<n>` with one commit for each task. - The plan, the task list and the decisions log. Rookery keeps them on its server and does not commit them. To put them in the pull request as `agent-plans/<n>/`, clear a repository setting in the portal. - A draft pull request. Its body holds the review and the result of each extra step. ## What Rookery does not do - It does not merge a pull request. - It does not push to your base branch. - It does not start work without an `approve` comment from a person with write access. - It does not use an LLM to decide if a comment is an approval. A fixed pattern decides. ## Repo stats The portal opens on the **Stats** tab of a repository. Select 30, 90 or 365 days. The tab shows: - Commits, authors and changed lines on the base branch. Merge commits are not counted. Rookery reads them from its clone of the repository. - The commits for each week (each month for 365 days), the top authors and the files that changed most. - What Rookery did: runs, planned issues, pull requests, reviews and cost. - The bot share: the part of the merged pull requests that Rookery opened. - The stars, forks, open issues and languages from GitHub. Rookery shows author names only. It does not show email addresses. The numbers can be up to 5 minutes old. ## Pages - [Getting started](getting-started.md): install the App and run your first issue. - [Workflow](workflow.md): the labels, the comments and what to do when a run fails. - [Configuration](configuration.md): control the agents, skills and steps for a repository. - [Safety and limits](safety.md): the rules that Rookery always follows.