Installation

Rauf is a CLI (plus an optional web dashboard) that installs and drives autonomous coding loops in your existing projects. The quickest way to install it is from npm; you can also build from source when you want the current development version.

npm install -g @garygentry/rauf   # the installed command is still `rauf`
npx @garygentry/rauf status .      # or one-off, no install

The package is scoped (@garygentry/rauf) because the bare rauf name is blocked by npm’s name-similarity filter; the installed command remains rauf.

This page covers the prerequisites, the build-from-source steps, verifying the install, adding rauf to a project, and the common first-run snags.

Prerequisites

Tool	Why rauf needs it
A coding-agent CLI (Claude Code by default)	Rauf spawns a fresh agent session for each loop iteration.
git	The runner commits the working tree after every successful iteration.
Bun	TypeScript runtime used to build (and run) rauf from source.
pnpm 9+	Workspace package manager — pnpm install / pnpm build.
Node.js >= 22	Required by the toolchain that builds the packages.

Rauf orchestrates an agent — it doesn’t implement one

Rauf is the loop runner; it doesn’t implement an LLM agent itself, it spawns one per iteration to read a backlog item, make changes, and run your verification command. The runner is deliberately separated from the agent it drives. Rauf is optimized for and defaults to Claude Code, so make sure claude works on its own before installing rauf.

Install from source

Clone the repository, install dependencies, and build all packages:

git clone https://github.com/garygentry/rauf.git
cd rauf
pnpm install
pnpm build

pnpm build compiles every workspace package (core, loop, cli, web). The build must succeed before the rauf command will run.

Make rauf available globally

Symlink the rauf command into ~/.local/bin:

bash scripts/install-global.sh

~/.local/bin must be on your PATH. If it isn’t, add it to your shell profile:

export PATH="$HOME/.local/bin:$PATH"

In-repo alternative: direnv

If you use direnv, running direnv allow inside the cloned repo adds scripts/bin/rauf to your PATH automatically while you’re in the directory — no symlink needed. The wrapper runs Bun directly on the TypeScript source, so it always reflects the latest build. This is handy when hacking on rauf itself; for using rauf across other projects, prefer scripts/install-global.sh.

Verify the install

rauf version

For a machine-readable check (useful in scripts and CI):

rauf version --json

{ "version": "0.6.0" }

If rauf version prints a version, the CLI is installed and on your PATH.

Add rauf to a project

Install rauf into an existing project. The installer auto-detects the tech stack (Node, Python, Go, Rust) and writes the loop artifacts and a .rauf.json config:

rauf install /path/to/my-project --yes

Install also writes two repository instruction files (both as idempotent, sentinel-bounded managed blocks that preserve any surrounding content):

• AGENTS.md — the host-agnostic cross-agent instructions read by Codex and other agents.
• CLAUDE.md — the Claude-optimized companion (includes Claude Task-tool delegation guidance).

--yes accepts the detected defaults non-interactively. You can override the detected commands with flags when they differ from the stack defaults:

Flag	Purpose
--test-cmd	Command the loop runs to verify tests.
--typecheck-cmd	Type-check command.
--lint-cmd	Lint command.
--build-cmd	Build command.
--format-cmd	Formatter / format-check command.
--gitignore-scripts	Add the installed scripts to .gitignore.

To scaffold a brand-new project instead of installing into an existing one, use rauf init:

rauf init /path/to/new-project --stack node-typescript

rauf init accepts --name, --description, --stack (node-typescript, node-javascript, python, go, rust, or custom), and --seed <file> to seed an initial backlog.

Troubleshooting

Symptom	Cause	Fix
rauf: command not found	~/.local/bin is not on your PATH.	Add export PATH="$HOME/.local/bin:$PATH" to your shell profile and reopen the shell.
Old behavior after editing rauf	Stale build — the compiled output lags the source.	Re-run pnpm build from the repo root.
rauf status reports NOT_INSTALLED	The project has no .rauf.json.	Run rauf install <path> (or rauf init <path> for a new project) first.

macOS Gatekeeper (compiled binaries only)

The build-from-source path above is the primary install. If a compiled rauf binary is ever distributed and macOS quarantines it as unsigned, clear the quarantine attribute before running it:

xattr -d com.apple.quarantine ./rauf

Next steps

• Your First Loop — add a backlog item and run an end-to-end loop.
• Core Concepts — the backlog, the loop, signals, and status vocabulary.