Signed tool-use records and verification CLI

Make a tool-use claim traceable to its evidence.

Record which tool version was used, what was observed, and the evidence behind the claim. Efficacy binds the record to signed, hashed artifacts so a later reader can catch changed files or evidence for the wrong version before relying on it.

Follow the quickstart See what a record lets you check

Verification checks integrity and artifact binding. Whether a claim is true still depends on the evidence and signer.

Check which tool a “pass” actually refers to

Illustrative excerpt from the documented demo-tool workflow. Fields and hashes are shortened here; this is not a complete, verifiable record or a measured performance claim.

1 · The claim being recorded “Passed” needs a version and evidence

The demo reports the same 12 checks passing, using 4,100 tokens without the tool and 2,900 with it.

Tool: demo-tool 1.2.3
Claim: 1,200 tokens saved.

Those are the example’s reported numbers, not facts established by signing them.

2 · Efficacy record excerpt The claim points to specific artifacts

"tool": {
  "name": "demo-tool",
  "version": "1.2.3",
  "hash": "sha256:…"
},
"measurement": { "tokens_saved": 1200 },
"verdict": "pass",
"evidence": {
  "url": "https://example.com/evidence/rec_demo.json",
  "hash": "sha256:…",
  "kind": "benchmark"
}

3 · The next reader checks Catch evidence for the wrong version

efficacy verify checks the supplied chain, key, tool bytes, and evidence bytes.

Binding check: Evidence naming demo-tool 1.2.30 cannot support a record naming 1.2.3. Verification reports check binding when that check fails.

A later agent can spot a version mismatch before relying on the claim, then read the evidence to judge the result.

Passing verification establishes integrity and binding, not that the measurement is correct or that the signer is trustworthy. The full workflow also shows how to retract a bad baseline.

Run the complete verification example

Install

npm i -g efficacy

Or run it once with npx efficacy. Node.js 22+. The package is efficacy on npm.

Start here

Docs: records, verify, and trust tiers
Specification: efficacy/0.3, the authority
Writing: notes from use

The loop

efficacy init writes one signed genesis line.
efficacy evidence writes the evidence file: what was run, what was observed, and the tool's hash.
efficacy record appends a use line that cites it, with a pass or fail verdict.
efficacy verify walks the file and names the first broken check, or a trust tier per record. To reproduce a check, obtain the record, the referenced artifact bytes, and the signer key the example names. Verify the binding, then inspect the evidence and decide whether you trust the signer.
efficacy retract withdraws a record that no longer holds. Nothing is deleted.

A genesis line opens the chain. It is not a win. Unsigned notes are hints. The README quickstart runs the whole loop, including a retraction.

The reference implementation lives in Catalyst-Forge-LLC/efficacy. The spec is CC0. The code is Apache-2.0.