brr

$ section install

brew

brew install hl/tap/brr

go install

go install github.com/hl/brr/cmd/brr@latest

build from source

git clone https://github.com/hl/brr
cd brr
make build

$ brr --help

Usage

brr <prompt> [flags]
brr [command]

Available Commands

completion  Generate the autocompletion script
help        Help about any command
init        Scaffold a project for brr
workflow    Run a multi-stage workflow

Flags

-h, --help             help for brr
-m, --max int          max iterations (0 = unlimited)
-n, --notify           send desktop notification on stop
-p, --profile string   profile from .brr.yaml
-v, --version          version for brr

$ examples

run a prompt file

brr prompts/build.md --max 20

resolve a named prompt

brr plan --max 3

inline prompt

brr "Fix all TODO comments in src/" --max 5

notify when done

brr build --max 20 --notify

run a workflow

brr workflow ship

restart a workflow

brr workflow ship --reset

$ cat .brr.yaml

Profiles are intentionally plain. Each one defines a command and argument list, and brr pipes the prompt to stdin. That keeps the loop runner agent-agnostic.

Prompt resolution order: existing file, then `.brr/prompts/<name>.md`, then your user config prompts directory, then inline text. 

default: claude

profiles:
  claude:
    command: claude
    args: [-p, --dangerously-skip-permissions, --model, sonnet, --max-turns, "200"]

  opus:
    command: claude
    args: [-p, --dangerously-skip-permissions, --model, opus, --max-turns, "200"]

  codex:
    command: codex
    args: [exec, --ephemeral, --dangerously-bypass-approvals-and-sandbox, --model, gpt-5.4, -]

$ cat .brr/workflows/ship.yaml

Workflows turn brr into an autonomous agentic pipeline. Define stages, point each at a prompt, and let the cycle-back loop close the feedback gap — build, verify, fix, repeat. Pair with pre-commit hooks or CI checks and the agent doesn't just think it's done, something external proves it.

Progress is saved to .brr-workflow-state.json after each stage. Interrupted workflows resume from where they left off. Use --reset to start fresh. 

stages:
  - prompt: spec       # requirements -> spec
    max: 3
  - prompt: plan       # spec -> implementation plan
    max: 5
  - prompt: build      # implement one task per iteration
    max: 100
    cycle: true        # restart here if later stages find issues
  - prompt: verify     # check against acceptance criteria
    max: 3
  - prompt: review     # audit changes for correctness
    max: 1
max_cycles: 3

$ ls -a .brr*

.brr-complete

The agent creates this file when all work is finished. brr detects it, stops the loop, and removes the file. Your prompt should create this as the last step when there are no items left to process.

.brr-needs-approval

The agent creates this file when it needs a human decision before continuing. brr stops the loop and prints the file contents (up to 4 KiB) so you can see what the agent is asking about. Resolve the issue, delete the file, and re-run.

.brr.lock

Prevents multiple brr instances from running in the same directory at the same time. Acquired automatically on start, released on exit. The file stays on disk between runs — this is intentional. Added to .gitignore by brr init.

.brr-workflow-state.json

Tracks workflow progress for resume. Written by brr workflow after each stage. Deleted on completion. Use --reset to discard and start fresh. Added to .gitignore by brr init.

three consecutive failures

brr aborts automatically instead of spinning forever on a broken task.

$ prompt shape

You are one iteration of a loop. Do one unit of work, then exit.

1. Read the state (a file, an API, a queue)
2. Pick one item
3. Do the work
4. Update the state (mark it done, commit, etc.)
5. If nothing left, create .brr-complete and exit