Tracefold
TraceFold is a tool that escrows the inverse of an AI agent's write action before the action lands, preventing irreversible changes. It issues verifiable receipts and can refuse or reverse effects. It is for developers building AI agents that need safety guarantees against destructive operations.
✨ Key features
- Pre-fact provenance: constructs inverse before action executes
- Tri-state verification: Verified, Refuted, Unknown/Unparseable
- Offline verification via standalone WebAssembly
- Command-line tool gx for undo and receipt verification
- TypeScript SDK for offline receipt verification
- Formal proofs in Lean 4 (154 theorems)
🎯 Use cases
- Prevent AI agents from making irreversible file changes
- Escrow and reverse write operations in agent tool calls
- Verify receipts offline without trusting a central server
- Implement deterministic approval gates in agent systems
📦 Installation
🧰 Requirements: Requires Node.js for SDK, Rust for CLI, or a browser for WASM verification; no API keys needed for the demo.
npm i @mahirhir/tracefoldcargo install tracefold🚀 Usage
import { readFileSync } from "node:fs";
import { verifyReceiptOffline } from "@mahirhir/tracefold";
const key = JSON.parse(readFileSync("key.pub.json", "utf8"));
const result = verifyReceiptOffline(
readFileSync("commit_receipt.json", "utf8"), key.key_id, key.public_key,
readFileSync("checkpoint.json", "utf8"), key.key_id, key.public_key
);
console.log(result.valid, result.checks.inclusion); // true "verified"
⚠️ Good to know
Excludes root/kernel-privileged writes, writes into its own state dir, and policies encoding wrong intent; also has unmeasured platforms (Windows native, OneDrive, SMB) and some failing tests.
❓ FAQ
How does TraceFold prevent irreversible changes?
It constructs the inverse of an action before the action lands; if the inverse cannot be built, it halts and escalates to human approval.
Can I verify receipts without internet?
Yes, verification runs 100% in-tab WebAssembly with zero network requests, or via the offline verifier in the SDK.
What is the gx command?
gx is the Rust CLI that provides commands like gx undo and gx receipt verify, used in the demo.
Is TraceFold free to use?
Yes, everything is free and stays free; there is an optional pay-what-you-want support channel via Stripe.
📊 Repository
🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.