Your agent says
it's done.
Check.
Readback is a command-line tool that checks coding agents' claims against files, GitHub, and web responses. It returns what it found, with evidence you can inspect.
Early software, with known verification limits.
readback verify claims.json --json
Two claims about proof.txt
Contains release-ready
Contains never-written
data.summary, excerpt
{
"verified": 1,
"contradicted": 1,
"indeterminate": 0
}exit 1One failed check is enough.One Go binaryRuns in your terminal
JSON resultsEvidence with each check
No model callsNo telemetry from the CLI
Open sourceReleased under MIT
01 / Get started
A small tool.
A short install.
Pick the route that suits your machine. Then try the file example below. It needs no account or credentials.
All releases, including WindowsOn macOS
brew install --cask joshduffy/tap/readbackAlready use Homebrew? That's the whole command.
On macOS or Linux
(
installer=$(mktemp) || exit 1
trap 'rm -f "$installer"' 0
curl -fsSL --proto '=https' --proto-redir '=https' \
https://readbackcli.dev/install -o "$installer" &&
sh "$installer"
)Downloads the script, checks the release checksum, and installs to ~/.local/bin. Add that directory to your PATH. Supports Intel/AMD and ARM64.
With Go 1.25 or newer
go install github.com/joshduffy/readback/cmd/readback@latestThis builds from source. The version currently displays as dev, even when you install a tagged release.
GitHub checks also need gh and an existing login. Start with gh auth login.
02 / How it works
A claim goes in.
Evidence comes back.
The agent writes down what it says happened. Readback checks those specific claims. You decide what the results mean for your task.
Write down the claim
A small JSON object says what to check: a file, a pull request, a commit, or a web response.
Ask the source
Readback checks the local file or calls the relevant service. The surrounding prose is ignored.
Read the evidence
Each claim is
verified,contradicted, orindeterminate. An unanswered check stays unanswered.
One file.
Two claims.
One useful failure.
Create a file containing release-ready. Then claim that it contains both that text and never-written.
The first claim passes. The second fails. The command exits 1. Readback does not average them into a success.
Run this in your shell after installing. Everything in this example stays on your machine.
{
"claim": {
"type": "file_exists",
"path": "proof.txt",
"contains": "release-ready"
},
"status": "verified",
"reason": null,
"evidence": [
{
"source": "local",
"call": "stat proof.txt",
"observed": {
"contains_found": true,
"mode": "-rw-r--r--",
"size": 14
}
}
]
}Actual fields from data.claims[0]. The condition sits next to the observation that answers it. The full record also includes its ID and check time.
(
mkdir readback-demo && cd readback-demo || exit 1
printf 'release-ready\n' > proof.txt
cat > claims.json <<'JSON'
{
"version": 1,
"claims": [
{
"type": "file_exists",
"path": "proof.txt",
"contains": "release-ready"
},
{
"type": "file_exists",
"path": "proof.txt",
"contains": "never-written"
}
]
}
JSON
readback verify claims.json --cwd . --json
echo "$?"
)03 / What you can check
Specific questions.
Inspectable answers.
Readback has six claim types. Each asks a defined question and records the answer it gets.
Read the claims schemafile_exists- Does this file exist? Does it contain the expected text?
pr_merged- Was this pull request merged into the intended branch?
commit_on_branch- Does this GitHub branch contain the commit?
checks_passed- Did GitHub's check runs and commit statuses succeed?
url_serving- Does this HTTPS response have the expected status, text, or headers?
deployment_servingExperimental- Does a Cloudflare deployment have the claimed commit and live evidence? Evidence requirements.
04 / Fit it into your workflow
Give your agent
something to fill in.
Install a skill for Codex, Claude Code, or Cursor. It teaches the agent to include a JSON block labelled readback-claims in its report.
readback install-skills --agent codexAlso: --agent claude, --agent cursor, or --agent all.
Then check the report: readback verify handoff.md --json.
05 / Before you rely on it
Useful details.
Actual limitations.
Readback is early software. The current version is 0.1.5. Inspect the evidence before using a result to approve a release.
Full limitations in the READMECan I use it as my only release check?
You still need to choose which claims establish that your task is complete. A passing file check says nothing about an omitted deployment. Put required checks in your own assertions file and inspect the returned evidence.
A deployment needs evidence of the claimed commit and an observation from the live site. A generic page marker cannot establish commit identity. Missing proof leaves the result indeterminate.
Does it send my data to a model?
No. The CLI makes no language-model calls and sends no telemetry. File checks run locally. GitHub and web checks contact the services involved in the claim, using your existing access.
What do the exit codes mean?
0: every claim verified and every required check met.1: a claim contradicted or a required check unmet.2: an unanswered check or no usable claims.64: invalid command or claims document.
If a run has both a contradiction and an unanswered check, it exits 1. The JSON still includes both results.
Will it understand a normal written report?
It reads JSON documents and Markdown blocks labelled readback-claims. It does not turn prose into checks. A report without a claims block exits 2, however confidently it was written.
Does it merge or deploy anything?
No. Verification checks what happened. It does not merge pull requests, deploy code, or send messages. The policy, hook, fleet, and memory commands are currently placeholders.
Start with one claim
Find out what happened.
Install Readback. Try the file check. Read the evidence.