Install

This page installs rafa and checks it works. It assumes the tools rafa drives are already on the machine: Bun, git, the GitHub CLI and Claude Code. If one is missing, start at Prerequisites, which links each tool's own install page.

1. Install the package

rafa is one package on npm, @open-tomato/rafa. Install it globally with either package manager:

$ npm i -g @open-tomato/rafa

Either one puts the rafa command on your PATH. The package declares no runtime dependencies, so the install fetches rafa alone.

2. Check it worked

rafa --version

rafa 0.47.0

rafa --help lists every subject and command, and marks with a 🪙 the ones that start Claude Code sessions.

3. Run the first check

rafa doctor runs every check a loop runs before its first session, and starts nothing. It works inside a rafa project, so set one up first, at the root of a repository you want to work on:

rafa init
rafa doctor

On a ready project it reports:

…
Preflight passed: rafa loop start would go on to its first session.
…
Effort sync: ok, local

A missing tool or login is named there, before anything is spent. Your first project walks rafa init and your first plan from here.

Keeping up to date

rafa itself. Update an npm or Bun install with the same package manager, asking for the newest version:

npm i -g @open-tomato/rafa@latest

bun add -g @open-tomato/rafa@latest

Two rafa commands look like they do this, and in 0.47.0 neither updates an npm or Bun install:

• rafa self-update builds rafa from a checkout of its own repository and installs that build under ~/.rafa/. Run anywhere else, it stops without building anything. It is for working on rafa itself.
• rafa update self is in development: it refuses, naming its issue (#715), and changes nothing.

Each project. A project set up with an older rafa may lack folders or board labels a newer one expects. Inside the project, after updating rafa:

rafa update current --dry-run
rafa update current

The first prints every change and writes nothing; the second applies them after one question, and records the version in rafa.lock at the project root, a small file meant to be committed. Below 1.0.0 it also crosses newer minors, so a lock at 0.34.1 moves to 0.36.0. The other rafa update actions (project, board, next, latest) are in development and say so. rafa update has the reference.

Next

Before you run it, then Your first project.