showwork

Check what an AI agent says it completed.

showwork records an agent's claims and runs deterministic checks. Its exit gate refuses a clean outcome close when declared acceptance checks fail. Each session keeps its own append-only, hash-chained receipt. Version 0.6.5 binds the Claude Code Stop hook to the task you started, and stops it from writing the same verdict on every turn.

Python 3.10 or newer. No runtime dependencies. MIT licensed.

A passing check only proves what it tests. Showwork cannot judge whether a requirement covers your request or a test matches its description. Read the evidence-scope incident for an example of that limit in our own use.

Try Check the proof to assess claim/check mismatches, or use the optional Python example and pilot readout. It is advisory and does not change showwork's deterministic verifier.

Quickstart

Use a new empty directory. The first close deliberately fails because the claimed file does not exist.

python -m pip install showwork

python -m showwork is the same CLI after install. Use it if showwork is not on PATH. The commands below use Bash quoting.

showwork start --session first-look --agent cursor
showwork require --session first-look --id config --scope artifact --description 'config/api.yaml exists' --type file_exists --path config/api.yaml
showwork claim --session first-look --claim "config/api.yaml exists" --type file_exists --path config/api.yaml
showwork finish --session first-look --status ok

Expected: exit code 2, a RED claims verdict, and a REFUSED message. The failed close is part of this example.

Create the file, retract the premature claim, and record a new one:

python -c "from pathlib import Path; p=Path('config'); p.mkdir(exist_ok=True); (p/'api.yaml').write_text('timeout: 30\n')"
showwork retract --session first-look --claim "config/api.yaml exists" --reason "file was not written yet"
showwork claim --session first-look --claim "config/api.yaml exists" --type file_exists --path config/api.yaml
showwork finish --session first-look --status ok

Expected: exit code 0 and Outcome: VERIFIED. This proves one artifact requirement. It proves no application behavior. For a broken function that a test catches, see the behavior quickstart.

Inspect the session:

showwork verify --session first-look --json
showwork audit

For a shell-independent example, see the Python quickstart.

How it works

flowchart TD
    accTitle: showwork outcome checks
    accDescr: Failed checks refuse a clean close and return to the work.
    A[Start a session] --> B[Declare acceptance checks]
    B --> C[Do the work and record claims]
    C --> D{Run checks}
    D -->|Pass| E[Record verified outcome]
    D -->|Fail| F[Refuse clean close]
    F --> C

Text equivalent: start, declare what must pass, do the work, record claims, and run the checks. Failed checks refuse a clean close. Fix the work or close as blocked; corrections append new records.

• Artifact checks observe files, paths, or other declared state.
• Behavior checks run declared test commands.
• Session snapshots detect changed or deleted files that active claims do not name, within the snapshot's scope.
• Receipt checks verify the chain and, when required, that Git tracks the session's evidence.

Distinct session slugs write distinct files under .showwork/sessions/ and .showwork/claims/. Reusing one slug requires one writer. See concurrency and the spec-v0.5 ledger specification.

Add it to a repository

showwork init

Review the generated Cursor rule, Claude Code Stop hook, and CI draft at docs/ci/showwork-verify.yml. Copy the CI draft into .github/workflows/ when ready. The Stop hook observes results; the explicit finish or CI gate enforces a close.

Cursor walkthrough · Claude Code adapter · CI setup

Check types

Use showwork <command> --help for your installed CLI. The specification defines check shapes and records; CI documentation explains command and network permissions.

Limits and trust

What this is not

Outcome verification does not detect reward hacking or read model activations. An agent can pass every declared check while gaming an evaluation. Chain-of-thought (CoT) self-report is not a substitute for independent checks of the actual outcome.

• Showwork verifies declared checks, not whether the work satisfies every part of the user's request. Requirements and tests still need review.
• A passing command can contain a weak test. A text match cannot prove application behavior.
• Hash chains detect changes relative to retained history or a trusted head hash. They do not prevent an attacker from replacing an entire unanchored ledger.
• Command restrictions are not a sandbox. Run untrusted code only in an appropriate isolated environment. Network checks are off by default in the GitHub Action.
• Receipts can contain paths and application data. Review them before publishing.
• Historical measurements describe their selected corpus. They are not a general detection rate or a compliance certification.

See evidence scope, legacy ledger migration, and the dated case study.

Documentation and help

Every pull request carries the committed .showwork/ receipt for the session that produced it. Receipt CI reports findings for review without blocking a merge; tests remain required. Repositories can opt into strict receipt enforcement. Read CONTRIBUTING.md for setup and the receipt gate.

Maintained by Patrick Hughes. Report a bug with the version, a minimal reproduction, and the expected result. Report vulnerabilities privately using the contribution guide.

README quickstart commands and documentation links are checked in CI. Source metadata defines the branch version; the PyPI badge links to the published release. MIT license.