Docs

Getting started

Try Roook in the browser with nothing to install, then run the CLI on your own repo. This is the short version; each part links to the guide with the details.

What you need

To try the example on this site: a browser. Nothing to install and no account.

To run Roook on your own repo, on your machine:

Python 3.12 or newer, and uv to install Roook.
Docker, running. Roook starts your app in a Docker sandbox.
git. Roook works on a copy of your repo and commits the fix to a branch.
IBM Bob Shell with your own BOB_API_KEY, for live runs.

Supported environments and setup, in detail

Try the example on the site

Open Try Roook and pick one of the two example repos: shop-app (Node.js) or minishop (Python, Roook's own small test shop).
Watch the run. It is labelled Recorded example run: Bob's answers are replayed from a saved real run, and the engine still runs live against the real app.
Answer when Roook asks: which rules to approve, and whether to apply the fix.

A recorded example run sends nothing to IBM Bob and needs no key. Guests get 3 runs a day. The site does not run your own repos: for those, use the CLI.

Try Roook

Install the CLI

$uv tool install git+https://github.com/tony19053000/rook

Roook is not on PyPI yet, so it installs from GitHub. Check that it is there:

$rook --version

For live runs, put your IBM Bob key in the BOB_API_KEY environment variable of the shell that runs Roook. The install guide shows how to keep it out of your shell history.

Install, upgrade, uninstall and IBM Bob setup

First run on your repo

From your repo's folder, run rook to open the interactive session. Or name the repo with rook run: a local folder, or a GitHub owner/name.

rook
rook run ./my-app
rook run owner/name

A local folder is copied into a workspace under ~/.rook/workspaces/ and the original is never changed. A GitHub owner/name needs rook login and the Roook GitHub App on that repo first; the GitHub Action guide has the steps.

If your app needs a value to start, such as an admin password, put it in an environment variable and pass the variable's name. The value is read from your environment, never from the command line.

$rook run ./my-app --setup ADMIN_PASSWORD

Roook asks before the steps that matter: approving the rules, applying a fix and opening a pull request. For a run with no questions, rook run ./my-app --ci --auto prints plain output, writes rook-report.json and rook-report.md, and exits 0 when every approved rule held, 1 when a rule is broken and 2 when the run did not finish.

What you see at each step

1 · Understand: The Scout, the Mechanic and the Mapper appear as characters while they read the repo, start the app in a Docker sandbox and map its HTTP API. If the app needs a setup value Roook was not given, it asks.
2 · Rules: The rules the Lawmaker proposed, each with its check and the Rule Critic's verdict. You approve all, none or some of them.
3 · Search: A progress row while the engine runs sequences of actions against your running app and checks every approved rule after every step.
4 · Shrink and prove: The failing sequence getting shorter, then the counterexample: the minimal steps, the values observed, and how many of the 10 replays reproduced it.
5 · Diagnose and fix: The Detective's file and line with its explanation. Roook asks before the Surgeon writes a fix, then shows the diff.
6 · Verify and ship: The four engine checks, each passed or failed, then the branch the fix was committed to, and the pull request for a GitHub repo.

Where the results land

rook/rook.yaml: The model of your app: actors, actions, state readers and the rules you approved.
rook/counterexamples/cx_001.json: Each counterexample, with everything needed to replay it exactly.
A regression test: A test in your project's own test framework, next to your existing tests, that fails on the bug and passes after the fix. If Roook cannot validate a native test, it falls back to a generated pytest file that replays the JSON.
A rook/fix-* branch: One commit with the fix, the regression test, rook/rook.yaml and the counterexample file. The branch is named after the counterexample, for example rook/fix-cx-001.

For a local folder, look in the workspace

Roook never writes to the folder you pointed it at. For a local folder, these files and the rook/fix-* branch are in the run's workspace, ~/.rook/workspaces/<run-id>/, which is a git repository of its own; nothing is pushed anywhere. For a GitHub repo they reach you as a pull request.