Prerequisites

rafa drives tools you already use instead of rebuilding them, so most of what it needs is those tools, installed and signed in before rafa itself. This page lists each one with what rafa uses it for, and links to its own install page, which stays current where a copy here would not. Once they are in place, Install installs rafa.

Bun

rafa runs on Bun, a JavaScript runtime, even when you install rafa with npm: no Node.js version runs the rafa command. The package declares Bun 1.3.14 or newer in its engines field; rafa runs no version check of its own, so stay at or above it.

Install it from Bun's installation page.

git

Every task a loop runs ends in a commit, and branches, worktrees and claims are git operations. Set a commit identity (user.name and user.email) for the repositories you run rafa in. rafa checks no minimum git version.

Install it from git's downloads page.

The GitHub CLI (gh)

rafa reads and writes GitHub only through gh: issues, the board, pull requests, CI readings, claims, and releases that push. A project with no GitHub remote runs without it, with the board and pull request readings left out. rafa checks no minimum version.

Install it from the GitHub CLI's site, then sign in (below).

Claude Code

Every command marked 🪙 starts Claude Code sessions through the claude command; rafa calls no model API directly. rafa doctor warns when the installed Claude Code is a different version from the one rafa's skill delivery was last checked against; it is a warning, not a minimum.

Install it from Claude Code's setup page, then sign in (below).

Optional: Docker and tmux

• Docker runs a rafa-hub container, the server a team's devices sync through. rafa itself does not need it. Install it from Docker's Get Docker page.
• tmux lets rafa stretch start open its three operators in one session; without it, the engineer starts in your terminal and the other two are printed as lines to run. Install it from tmux's installing page.

Logins and tokens

GitHub. Sign in once with gh auth login. rafa doctor checks gh auth status for the remote's host when the project's pull request provider is gh. Two commands need more than the default scopes:

• rafa init --board --project and rafa board sync work on a GitHub project, which needs the token's project scope. Add it with:

  gh auth refresh -s project

  A loop on another machine that changes labels needs the scope there too, or its changes reach the issues and not the project; rafa board sync catches up afterwards.

Claude. Sign Claude Code in, with a Claude plan or an API key. Every session rafa starts counts against that plan's limits, or is billed to the key (Before you run it). [verify: how a Claude Code sign-in is checked by rafa doctor --deep; not run here]

A registry, for publishing. rafa release publish runs npm publish (or the command release.publishCommand names) under your own registry login. At level 2 of the release ladder, CI publishes through npm trusted publishing instead, which needs npm 11.5.1 or newer and no token on your machine (The release flow).

A hub token, for a team hub. Under effort.sync: service, each device sends a GitHub token from the system's secret store, named by hub.tokenSecret (Connect devices).

Repository permissions

What your GitHub account needs on the repository, by what the command does. Branch protection and organisation rules can ask for more.

Command does	Commands	Needs
Reads the board, issues, pull requests or CI	rafa roadmap, rafa status, rafa issue list/show, rafa pr current/show/list, rafa ci status, rafa epic show, rafa board list	read access
Pushes a branch and opens a pull request	rafa loop start, rafa pr open, claims	write access
Merges a pull request	rafa pr merge	write access, and whatever the base branch's protection requires
Marks a spec ready, edits an issue	rafa issue ready, rafa issue edit	ready: the issue's author must have write access, and the account running it must be able to change labels. edit: both the author and the account running it must have write access or be in board.trustedAuthors
Sets up the board	rafa init --board (labels, spec template, pinned Roadmap issue, epic guard workflow)	write access [verify: pinning an issue and adding a workflow may need more; not run here]
Pushes a release	rafa release settle under release.settle: push, rafa release tag --push	write access to the base branch; a protected base uses release.settle: pr instead
Sets the CI publish variable	gh variable set RAFA_RELEASE_PUBLISH --body ci	[verify: the role GitHub requires to set a repository variable]
Syncs through a hub	effort.sync: service	admin, maintain or write access on the repository the hub names

A spec issue opened by an account without write access is never planned from: an issue's text ends up in an agent's prompt.

Check it

Once rafa is installed (Install), run, inside a project:

rafa doctor

It prints every check, names each missing tool or login, and exits 1 where rafa loop start would halt. rafa doctor --deep goes further and reads what a loop session can reach: its settings, PATH, the providers gh answers under the session's environment, and the tools the project's stack needs.