Metadata-Version: 2.4
Name: showwork
Version: 0.6.4
Summary: Falsifiable claims and deterministic verification for AI agents. Make your agents show their work.
Author: Patrick Hughes
License-Expression: MIT
Project-URL: Homepage, https://github.com/bmdhodl/showwork
Project-URL: Issues, https://github.com/bmdhodl/showwork/issues
Keywords: ai-agents,verification,attestation,audit-trail,compliance,agent-governance
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# showwork

Check what an AI agent says it completed.

[![CI](https://github.com/bmdhodl/showwork/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bmdhodl/showwork/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/showwork)](https://pypi.org/project/showwork/)
[![Python versions](https://img.shields.io/pypi/pyversions/showwork)](https://pypi.org/project/showwork/)
[![License: MIT](https://img.shields.io/github/license/bmdhodl/showwork)](LICENSE)

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.4 refuses the close when add(2, 2) returns 5, then passes the same check after the repair. Declare the check before the first claim.

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](docs/evidence-scope.md) for an example of
that limit in our own use.

Try [Check the proof](https://bmdpat.com/tools/showwork/check-proof) to assess
claim/check mismatches, or use the optional [Python example and pilot readout](docs/check-proof.md).
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.

```bash
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.

```bash
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:

```bash
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](docs/quickstart-behavior.md).

Inspect the session:

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

For a shell-independent example, see the
[Python quickstart](docs/quickstart-python.md).

## How it works

```mermaid
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](docs/concurrency.md) and the
[`spec-v0.5` ledger specification](SPEC.md).

## Add it to a repository

```bash
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](docs/walks/cursor.md) ·
[Claude Code adapter](docs/claude-code.md) ·
[CI setup](docs/ci.md)

## Check types

| Type | What it checks |
| --- | --- |
| `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 |

Use `showwork <command> --help` for your installed CLI.
The [specification](SPEC.md) defines check shapes and records;
[CI documentation](docs/ci.md) 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](docs/evidence-scope.md),
[legacy ledger migration](docs/legacy-baseline.md), and the
[dated case study](docs/case-study.md).

## Documentation and help

| You want to | Start here |
| --- | --- |
| Find guides and references | [Documentation index](docs/README.md) |
| Run a quickstart on Windows or another shell | [Python quickstart](docs/quickstart-python.md) and [behavior quickstart](docs/quickstart-behavior.md) |
| Gate CI on committed receipts | [CI guide](docs/ci.md) |
| Wrap an agent command | [Adapters](docs/adapters.md) |
| Read or implement the ledger format | [Specification](SPEC.md) |
| Review measured results | [Case study](docs/case-study.md) and [measurement method](docs/false-done-rate.md) |
| Navigate with an AI assistant | [AI documentation index](llms.txt) |
| Contribute | [Contributing](CONTRIBUTING.md) |
| Inspect releases | [Changelog](CHANGELOG.md) |

Every pull request carries the committed `.showwork/` receipt for the session
that produced it. A pull request without one is not reviewed.
Read [CONTRIBUTING.md](CONTRIBUTING.md) for setup and the receipt gate.

Maintained by [Patrick Hughes](https://github.com/bmdhodl).
[Report a bug](https://github.com/bmdhodl/showwork/issues) with the version,
a minimal reproduction, and the expected result. Report vulnerabilities
privately using the [contribution guide](CONTRIBUTING.md#security).

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](LICENSE).
