[bmdpat]
Download BMD free

OPEN SOURCE / PYTHON

showwork

Make the agent name its checks. Run them. Keep the receipt.

showwork records explicit file and command checks, reruns them, and can refuse a successful close when declared acceptance checks fail. The proof covers those checks. The quality and coverage of the tests still need review.

Try a check that fails

FIRST RUN / 0.6.5

Try a check that fails

Ask for one line in a file. Try to close before writing it. Then fix the file and run the same check again.

You need Python 3.10 or later. Create a new empty folder and open a terminal there. Use a fresh folder each time so old files and receipts cannot satisfy this example.

1. Install in that folder

Choose your terminal. Run each line separately and keep that terminal open for the rest of the example.

Windows Command Prompt
Windows setup
python -m venv .venv
.venv\Scripts\activate.bat
python -m pip install showwork==0.6.5
macOS or Linux (Bash or Zsh)
macOS or Linux setup
python3 -m venv .venv
. .venv/bin/activate
python -m pip install showwork==0.6.5

2. Declare the result you expect

The requirement checks that result.txt contains the line “Ready for review”. You have not created that file yet.

Declare the check
python -m showwork --root . start --session first-look --agent human
python -m showwork --root . require --session first-look --id result --scope artifact --description "result.txt contains the requested line" --type file_contains --path result.txt --pattern "^Ready for review$"

3. See the close refused

Run the missing-file check
python -m showwork --root . finish --session first-look --status ok

Expected exit code: 2. The output says RED, UNVERIFIED and REFUSED because result.txt is missing. This failure is intentional. Continue with the next step.

4. Write the file, then verify

Fix and verify
python -c "from pathlib import Path; Path('result.txt').write_text('Ready for review', encoding='utf-8')"
python -m showwork --root . claim --session first-look --claim "result.txt contains the requested line" --type file_contains --path result.txt --pattern "^Ready for review$"
python -m showwork --root . finish --session first-look --status ok

Expected exit code: 0. The final command reports GREEN, Outcome: VERIFIED and session.finish recorded: first-look.

The two passing checks are the requirement and its matching claim. They check the same line. This does not prove application behavior or that your requirements cover the whole task.

Still failing? Read the named check in the output. Confirm you are in the same folder and that result.txt contains the expected line. Fix the file, then rerun finish. If you entered the requirement incorrectly, restart this example in a new empty folder. Do not treat a failed close as completed work.

Used this on a real task? Share an optional pilot report with the finished receipt and an intentional refusal. A repeat report should cover another task in the same project at least seven days later. Review and redact before posting. The practice example above does not count as product adoption.

CHECK TYPES / 8

Each check can fail.

A claim names one of these checks. The check runs at finish and again in CI. Mirror of showwork claim --type.

file_exists
A file exists.
file_contains
A file matches, or does not match, a regular expression.
path_moved
The source is gone and the destination exists.
frontmatter
A frontmatter field has the expected value.
glob_count
A path count meets the declared comparison.
command
An allowed Python script exits as expected.
http_probe
An HTTP response has the expected status and optional text.
git_state
The local Git state matches declared conditions.

LIMITS

A passing check only proves what it tests.

  • showwork cannot judge whether a requirement covers your request, or whether a test matches its description.
  • It does not detect reward hacking. It does not read model activations.
  • It does not judge content quality. Those checks need task-specific tests that you write.
  • The receipt is local. Nothing leaves your machine unless you commit it.

RELEASE 0.6.0

A passing check proved too little.

GolfFly exposed weak checks in my own workflow. This release separates a claim from the check that supports it, requires declared acceptance checks, and checks that the complete receipt shipped. The 0.6.1 update adds a final integrity check after tests run and an explicit migration option for damaged history.

Read the 0.6.0 release notes

THE LOOP

One of three tools.

AgentGuard caps the spend during the run. showwork checks the claims after it. BMD shows the runs in one Windows workspace. Each tool works on its own.

Open AgentGuardOpen BMD

FAQ

Questions

What does showwork verify?
Declared checks against files, paths, commands, HTTP responses, and Git state. It records the result in an append-only receipt. It does not verify intent or quality.
Which agents does it work with?
Any agent that can run a shell command. The repository ships a Cursor rule, a Claude Code Stop hook, and a CI workflow draft.
Does it send data anywhere?
No. The receipt is a local file under .showwork/. Commit it when you want the record in the pull request.
Is it free?
Yes. MIT license, no account, no hosted service.
Source and documentationPython package

Feedback

Bug or suggestion? Include the version. Leave out private data.

Send Show Work feedback

Opens your email app, or write to pat@bmdpat.com.

Get product release emails

Release notes and upgrade steps.

Get release emails for AgentGuard, Show Work and BMD Desktop, plus the field kit and Friday notes when there is something worth sharing. One-click unsubscribe stops all BMD Pat emails. No account needed. Privacy.