BeforeDone

Make coding agents prove they're done.

Fresh evidence before completion. A replayable incident report when things go wrong.

Install BeforeDone View on GitHub
illustrative receipt · real v1 schema
$ beforedone check test

PASS Evidence receipt is current

check_id
test
argv
["go", "test", "./..."]
exit_code
0
fingerprint
sha256:7f3c2e9a…d6f8e
verdict
PASS

Bound to the configured relevant files, verifier argv, and current contents.

No fresh evidence.
No credible done.

BeforeDone evaluates explicit verifier results against their declared relevant-file scope. It asks Codex for one corrective continuation when the proof is missing, failed, or stale.

  1. 01

    Agent says done

    A completion claim reaches the Stop Hook.

  2. 02

    Receipts checked

    Required checks are matched to the current relevant-file fingerprint.

  3. 03

    Missing or stale

    Codex receives exactly one continuation with the checks it must run.

    ONE CONTINUATION
  4. 04

    Fresh check passes

    The new receipt matches the current declared relevant files.

    PASS
  5. 05

    Completion allowed

    The final claim now has inspectable support.

Evidence receipt anatomy

A receipt records what actually ran, its exit status, and which configured relevant files were fingerprinted.

{
  "schema_version": 1,
  "check_id": "test",
  "argv": ["go", "test", "./..."],
  "exit_code": 0,
  "relevant_files_fingerprint": "sha256:7f3c…d6f8e",
  "verdict": "PASS"
}

Find the first observable divergence.

Timeline, diff, receipts, logs, and corrections — without pretending to recover hidden reasoning.

Open the example report
illustrative report view · open the real report above local HTML
  1. 001
    ToolStartedgo test ./...
  2. 002
    ToolFinishedexit: 1 · parser edge case failedFIRST OBSERVABLE DIVERGENCE
  3. 003
    AgentStoppingmissing fresh test receipt
  4. 004
    User correctionhandle escaped delimiters

Event 002 · ToolFinished

command
go test ./...
exit
1
stderr
expected escaped delimiter to remain literal
evidence
log sha256: e3b1…6f9a

One core. Choose one Codex route.

The CLI is the source of truth and is always required. Then choose exactly one integration: the Git Marketplace Plugin for hooks plus both bundled skills, the standalone Skills Pack for a manual workflow, or project-local hooks from beforedone setup codex. Combining routes duplicates hooks or workflows.

Install the local evidence engine

Works on Windows, macOS, and Linux. From the target Git repository, run beforedone init, review .beforedone.yaml, then run beforedone doctor.

go install github.com/rrrrrredy/beforedone/cmd/beforedone@latest
Download release archives

Project-local hook alternative

Instead of the Plugin or standalone Skills, run beforedone setup codex, trust the project hooks with /hooks, and start a new task. Remove them with beforedone setup codex --remove.

For upgrades, uninstallation, data removal, and pinned versions, follow the complete README.

Local evidence.
Inspectable rules.

BeforeDone is a local guardrail for accidental early completion and stale evidence. It is inspectable, but it is not a sandbox or an attestation boundary against a malicious process running as the same OS user.

  • 01No telemetry
  • 02No cloud account
  • 03Imported replay cases never control commands
  • 04Apache-2.0

FAQ

Can log text forge a PASS?

Not through the supported check flow. A word such as “PASS” in output cannot override a non-zero exit; beforedone check records the process result and current fingerprint. This is not protection from a malicious same-user process that can read the key, change policy, and rewrite local evidence.

Does BeforeDone decide what to test?

No. BeforeDone verifies project-approved commands and keeps their evidence fresh; it does not infer whether they fully cover a natural-language requirement. Ask Codex to map the task to existing tests or a focused regression test, review the generated .beforedone.yaml, and report any uncovered criterion as unverified.

Why Apache-2.0 rather than MIT?

Both are permissive licenses that allow commercial use, modification, and redistribution. Apache-2.0 also provides an explicit patent license and clearer contribution and notice rules, which fit an extensible developer tool. It does not grant rights to the BeforeDone name or logo.

Is a receipt tamper-proof attestation?

No. The key, configuration, and runtime artifacts are local. A malicious process with the same user and repository write access can manufacture a self-consistent PASS. BeforeDone targets fallible Agents and stale claims; hostile Agents require an external trust boundary.

Does replay rerun the model?

No. Analyze mode replays BeforeDone's deterministic decisions. Verify mode can rerun configured checks in a temporary worktree only after explicit --execute.

Does BeforeDone recover chain of thought?

No. It reports only what observable evidence supports: an exact event must explicitly match a verified failing Receipt, a time window must enclose that check, and weaker evidence is marked unlocated. Generic command failures or later corrections do not become invented causality.

Does it isolate verifier network access?

No. Checks and explicit replay execution use the network, credentials, filesystem, and process permissions available to the current user.

Prove it before done.

Project siterrrrrredy.github.io/beforedone/ GitHub repositorygithub.com/rrrrrredy/beforedone