Skip to main content
Go from nothing installed to a pull request you can review. Allow about 10 minutes, plus the time PRFlow spends on the change itself. For the longer explanation behind each step, follow Getting Started instead.

​
Before You Start

You need a GitHub repository you can push to, Claude Code or Codex, and five tools on your PATH.
Python must be 3.11 or newer, and bash must be a POSIX Bash. On macOS, /usr/bin/python3 is often 3.9 — check with python3 -VV and install a newer Python if needed. On Windows, use WSL Bash, Git Bash or MSYS2 Bash. gh auth status must report an account that can read issues and create branches, comments and pull requests in the repository you plan to change.
PRFlow does not need a configuration file to run locally. Every setting has a built-in default.

​
1. Install the Plugin

Start a new Claude Code session, then enter /prflow:. Expected result: the completion menu offers PRFlow skills.
The marketplace is named devflow-marketplace on purpose. The plugin is named prflow. The walkthrough below uses Claude Code’s /prflow:<skill> spelling. In Codex, replace it with $prflow:<skill>, or select the skill from /skills in Codex CLI.

​
2. Set Up Your Repository

From anywhere inside the repository you want to change:
This step is recommended, not required. It writes .prflow/config.json, detects the build, test and lint tools your project already uses, grants them to PRFlow and checks your prerequisites. It finishes by reporting the dependency check:
If a tool is missing, initialization tells you which one and what to install. The configuration it already wrote is kept, so you install the tool and continue. Review the diff before you commit it. /prflow:init does not commit anything for you.

​
3. Create an Issue

Skip this if you already have an issue with clear acceptance criteria.
PRFlow reads your repository, asks the questions it cannot answer from the code, then saves the issue draft to a file and shows you its path (print the full draft in chat on request). Nothing is created until you approve that exact draft. Approve it, and PRFlow creates the issue and tells you its number.
Acceptance criteria are what PRFlow checks its own work against later. An issue with none still runs, but there is nothing for that check to test. Keep them in the draft.

​
4. Implement It

Replace 123 with your issue number.
PRFlow creates a branch named issue-123-<title-slug>, then posts a single progress comment to the issue and keeps it updated for the whole run. That comment is the workpad. Abridged, it looks like this:
The status glyph tells you where the run stands at a glance: When the run finishes, you have a branch, a pull request that closes the issue and a workpad recording what was verified and anything PRFlow could not settle.

​
5. Review and Merge

Read the pull request the way you would read a colleague’s: the code, the tests, the documentation and the acceptance-criteria evidence in the workpad. For a second opinion from a fresh review with no memory of building the change:
That returns findings and a verdict. Then merge it yourself. PRFlow never merges.

​
If a Run Stops

A run that ends with 👎 Blocked is telling you something specific. Common causes are an issue that depends on another open issue, a bug PRFlow could not reproduce, an acceptance criterion that does not pass, or a verification command it is not permitted to run. Read the reason in the workpad, resolve it and run the same command again. PRFlow picks up from the last recorded checkpoint. Troubleshooting covers each cause and its fix.

Workflows

Every command, what it is allowed to change and when to use it.

How PRFlow Works

The lifecycle, the review system and where your control points are.

Configuration

Set the base branch, tool permissions, review thresholds and documentation paths.

Cloud Runs

Start PRFlow from a GitHub comment instead of your terminal.