Agent guide

rf is built to be driven by programs, not only read by people. Three properties make it safe to script.

1. Learn the surface once

rf capabilities emits the full machine contract as JSON: every verb, flag, exit code, warning code, and output schema. An agent reads it once and never has to discover behavior by trial and error.

rf capabilities --json

Do not hardcode the surface. Read it, and branch on the contract_version in meta (currently 2). A breaking change bumps that number.

2. Trust the exit codes

Exit	Meaning	Retry?
`0`	Success, including empty results (`data: []`)	No
`1`	User-input error (bad flags, missing args), or a failing self-check	No — fix the call
`3`	Tool-environment error	No — fix the environment
`5`	Conflict: a paged result’s snapshot changed under the cursor	Yes — restart with the emitted command
`6`	Internal defect caught by the totality wrapper	No — report it

“No matches” is exit 0, never an error. Do not treat an empty result as a failure. Exit 5 is the only retryable code. See Exit codes.

3. Parse one envelope

Every verb — capabilities included — emits the same JSON envelope. Read ok and data; read warnings to learn what a naive search would have missed; read commands for the paste-ready rg invocations that reproduce each recovery. See the JSON contract.

rf content DB_DSN . --json | jq '.data[] | select(.surfaced_by != "default")'

Output is deterministic

rf honors SOURCE_DATE_EPOCH and content-addresses its request_id and data_hash. With a fixed epoch and the same inputs, the envelope is byte-identical across runs — safe to snapshot in a golden test.

SOURCE_DATE_EPOCH=0 rf content DB_DSN . --json > a.json
SOURCE_DATE_EPOCH=0 rf content DB_DSN . --json > b.json
diff a.json b.json && echo identical

Set NO_COLOR to strip ANSI styling from the human render.

It never crashes on you

Any internal fault is caught by the totality wrapper and returned as an error envelope with exit 6 — never an uncaught crash or a partial write to stdout. A missing external oracle (git, ast-grep) degrades to a warning, not a failure.

Self-check in place

rf conformance --json runs the release self-check profile against the running binary and emits a verdict set (pass / fail / not-applicable, with a reason for each). Exit 0 means no failures. Use it as a smoke test after install or in CI.