rafa pages
- rafa
- rafa
rafa
A command-line tool that runs a plan through Claude Code, one session and one commit per task, then opens a pull request and waits for CI.
rafa runs a plan from your terminal. A plan is a markdown checklist of tasks; rafa starts one Claude Code session per task, commits each task's work, then pushes the branch, opens a pull request and waits for CI, the continuous-integration checks the repository runs on it.
rafa is alpha, at version 0.47.0. It is a working example from Open Tomato's research, built with rafa itself, and commands, files and defaults still change between versions. Read Before you run it once before your first loop.
What it does
Most of the work around the agent is done by code, not by the agent. Code picks the next task, makes the branch, writes the version and decides whether a pull request is green. The agent is asked for the task's own work, and every task reports back what it did, what it found and what blocked it.
This is the default sequence, the most common case; The cycle walks it. Workflows become configurable before 1.0, once workflow config lands (#71, #119). The config shape is [TBD: the workflow config shape].
rafa drives tools you already use: git, the GitHub CLI (gh) and GitHub Issues. GitHub Issues is the only tracker that works today.
Install
rafa is one package on npm, @open-tomato/rafa, and runs on Bun. Install installs it and runs its first check; Prerequisites lists the tools it drives, which go on the machine first.
Where to start
The pages climb a range, from one person on one project to an organisation. Each step is opt-in, so stop at your own step.
| Your situation | Read |
|---|---|
| Setting up a machine | Prerequisites |
| Trying rafa on a side project | Install, Your first project, then The cycle |
| Letting rafa take the next step, or running a batch as a sprint | Subjects and workflows, rafa next, Stretches |
| Looking up a command and its flags | Command map |
| Changing how rafa behaves in your project | Configuration |
| Releasing versions from the branches rafa merges | The release flow |
| A team grouping specs into features, or several teams in one repository | Epics and boards |
| One project on two machines, or a team sharing records | Several devices |
| Contributing to rafa, or writing an add-on | Repository layout and Add-ons |
One package, one repository
You install one package, @open-tomato/rafa. Its repository, open-tomato/rafa, is a monorepo: one repository holding several packages, each with its own tests. Only the command-line package publishes from rafa itself, and it bundles rafa's core and features; add-ons, once they exist, publish on their own. The hub server and its client module live in the same repository but stay outside that bundle. Nothing about the split changes what you install or type, and Repository layout explains it for contributors.
Feedback and bug reports go to the issue tracker. The order things are built in is the pinned Roadmap issue.