Testigo — From Intent to Proof
Testigo is an open protocol for traceability, compliance and verification of
actions executed by humans and AI agents, together.
Its purpose is to guarantee that every significant action can demonstrate:
- why it was performed;
- which human intent originated it;
- which requirement it was fulfilling;
- who — or which agent — executed it;
- what the human approved (and why);
- what evidence it produced;
- and what final result was deployed or used.
Testigo is not a task manager, a CI/CD platform, a coding agent or a payment
system. It is a trust layer that connects the original intent with the
execution and the verifiable evidence of the outcome. Witness, not gatekeeper:
it records; it never orchestrates or blocks.
The chain
intent (prompt / ticket)
→ turn (agent works)
→ human approval (allow/deny + reason)
→ tool results
→ evidence (working-tree snapshots, files changed)
→ turn end
→ signed proof packet → anyone verifies, no install
Every link is an event in an append-only, sha256 hash-chained ledger (one per
project, local-first). A segment of that ledger exports as an
in-toto Statement signed as a
DSSE Ed25519 envelope — the
proof packet — verifiable with the standalone HTML verifier in this repo,
or any DSSE tooling.
Quickstart: verify the example
- Open the hosted verifier at
https://cyl-castillo.github.io/testigo/verifier/testigo-verifier.html
(or
verifier/testigo-verifier.html
locally). No install; verification runs entirely in your browser — the
page makes no network requests with your packet.
- Drop
examples/demo.proofpack.json on it.
- You should see: signature valid, subject digest OK, hash chain intact —
including one redacted event (linkage verified, content declared
unverifiable), one stub (an out-of-case event pruned to hashes), and a
declared RFC 3161 timestamp (a real freetsa.org token over the packet's
signature; the page checks the imprint and hands you the token plus the
openssl commands rather than pretending to verify CMS in the browser).
Spec
The protocol is specified in SPEC.md (v0.1, draft). The predicate
schema lives in schema/predicate-v0.1.schema.json.
Implementing a verifier? The conformance suite has golden
vectors isolating every verification step — including valid signatures
wrapped around internal defects — plus a zero-dependency reference verifier
(node conformance/verify.mjs).
Reference implementation: agent-console
(≥ v0.48.0) — captures the ledger ambiently from Claude Code / Codex sessions
(prompts, approvals, tool results, per-turn diffs), exports and signs packets,
and stamps console-made commits with Testigo-Case: trailers resolved from
ledger evidence.
Packets can also commit to records held elsewhere — the Claude Code
transcript at each turn end, an Anthropic Compliance API export, a GitHub
agent session log — as external_evidence events (SPEC §1.7): the chain
carries the record's location and sha256, a receiver with the platform's
copy recomputes it. This is how a packet composes with what the platforms
already log instead of competing with it.
Packets also record how the turn ended: a check_run event when the
agent runs a recognized test or check command (passed or failed, exit code,
sha256 of the full output) and a commit event when the work reaches git
(SPEC §1.7). They are declared by the producer and the verifier labels them
that way; what makes them checkable is what they bind — the output digest
and the commit sha.
The engine-neutral reference core — ledger, export, verification, timestamps,
external evidence — lives in packages/core; adapters per
engine build on it (the Claude Code plugin ships a vendored copy, see
#25 for the Codex and
other plugins that follow).
Lightweight capture without the console: cli/ is a zero-dependency
Node CLI that witnesses any Claude Code session via hooks, links cases, and
exports signed packets — with the capture-scope differences
stated plainly.
Install it as a Claude Code plugin (this repo is its own marketplace):
/plugin marketplace add cyl-castillo/testigo
/plugin install testigo@testigo
Honesty by design
Testigo prefers a smaller true claim over a bigger false one:
- The local ledger is tamper-evident, not tamper-proof — signing happens at
export, and a packet proves segment integrity + who signed it, not that the
ledger is complete.
- The event→turn binding is heuristic (same terminal between a prompt and
its stop), not cryptographic. The spec says so.
- Redacted events keep their original hashes: chain linkage stays verifiable,
content verification is explicitly reported as unavailable.
- The packet embeds its public key for convenience; the trust anchor is the
key id compared out-of-band with the publisher.
Real-world case study: a production deploy, witnessed
On 2026-07-15, a production deploy of Fixy (a Uruguayan
services marketplace operated with AI agents) was verified through a Testigo-
recorded session: one human intent (/fixy-status), three agent commands —
each individually approved by a human — three captured results (services,
API health, release state), and an empty turn diff proving the verification
was read-only. Chain intact, packet signed and verified.
A redacted packet of this session is published at
examples/fixy-deploy-verification.proofpack.json
— drop it on the verifier: the human intent, the three approval decisions and
the empty turn diff are fully verifiable; the agent's commands and outputs are
redacted per the protocol (payload excluded, chain linkage intact, reported as
such). The un-redacted packet stays private; both are signed by the same key:
| |
|---|
| event sequence | prompt → snapshot → (approval_request → approval_decision → tool_result) ×3 → turn_end |
| human approvals | 3/3 commands, each with an explicit decision |
| turn diff | files: [] — read-only, provably |
| digest (private, full) | f8d7db3fff68a80dbc545acac6f4cb08ece4b5295f709235a4491fd5025d9e72 |
| digest (published, redacted) | af21a0b7bfe48022764831415f1c82f45211f0b886ad59bbe4a19842308e0ceb |
| signer key id | 8caf09075df11abbbdea5cd1d120a5654d8d1ce2a32e2a6f018dde557c5014da |
| generator | agent-console/0.79.0 (re-exported 2026-09-16 from the same ledger, after the redactionCount fix; the redacted segment digest is unchanged) |
That a proof can be referenced without being revealed is part of the design:
the digest and key id above commit publicly to evidence that can be disclosed
selectively later (per-event redaction keeps the chain verifiable).
Status
- Spec: v0.2 (draft; additive over v0.1 — the process context of §2.6:
provider, context artifacts, session window, owner — mirrors the FINOS
Agentic Process Evidence shapes; packet format and predicate type URI
unchanged, see docs/ape-mapping.md).
- Spec v0.1: field names and predicate type are stable within v0.1.
- Reference implementation: shipping since agent-console v0.45.0 (ledger),
v0.46.0 (turn results), v0.47.0 (packets + verifier), v0.48.0 (timelines +
commit trailers), v0.49.0 (pre-sign redaction review — the published case
study below was produced with it).
- Spec'd and additive: git-ref ledger anchoring (§1.6), RFC 3161 timestamp of
the packet signature (§2.5 — the demo example carries a real token).
- Roadmap: sigstore keyless signing, requirement links beyond Jira,
cross-project cases.
License
MIT — see LICENSE.
