Tracekit

Tamper-evident records of what your AI agents actually did.

Every tool call is checked against your policy before it runs, then signed and hash-chained by a signer the agent cannot control. Change, delete or reorder anything afterwards and verification fails.

Why

Agents run commands, edit files and call APIs with your permissions. Afterwards, the record of what they did is usually a log or a transcript the agent's own user can edit or delete, which makes it weak evidence. Tracekit writes that record so it can be checked by anyone, offline, without trusting the agent or the machine it ran on:

• Before an action: the policy gate blocks it (deny), holds it for a human (ask) or marks it (flag).
• As it happens: a separate signer, which holds the key and assigns sequence numbers, signs every event into an append-only hash chain. The agent never holds the key.
• Afterwards: checkpoints go to a witness, and a .tkb bundle verifies offline. Edits, deletions, reordering and a quiet rebuild of the whole log are all detected.

Quickstart

pip install tracekit-ai
tracekit demo               # exit 0

tracekit demo needs no API key, root or config. It runs a scripted agent that is told to upload .env, shows the block, exports the run, verifies it, then edits one recorded command in a copy and shows verification fail.

Trace your own Claude Code sessions (dev mode: the signer runs as your user):

tracekit init --dev
tracekit observe            # the live view above, on http://127.0.0.1:7777
tracekit export --last -o run.tkb
tracekit verify run.tkb --key ~/.tracekit-signer/ledger/signer.pub --witness git:$HOME/.tracekit-signer/witness

Or check the shipped sample bundles with the verifier alone:

tracekit verify docs/sample/demo-run.tkb --key docs/sample/signer.pub            # exit 0
tracekit verify docs/sample/demo-run-tampered.tkb --key docs/sample/signer.pub   # exit 1

What you get

How it works

flowchart LR
    A[Agent] --> H[Hooks / SDK]
    H -->|policy gate| S["Signer (tracekitd)"]
    S --> L[Ledger]
    L --> C[Checkpoints]
    C --> W[Witness]
    L --> B[".tkb bundle"]
    B --> V[Offline verify]

• Hooks and SDKs run before and after each tool call (coding-agent hooks) or around the calls you wrap (Python and TypeScript SDKs). The policy decision is made, and signed, before the tool runs.
• The signer holds the key and assigns sequence numbers. In Linux system mode it runs as its own OS user, so the agent's user cannot read the key, change the ledger or modify the code that records it.
• The ledger is append-only JSONL: each record carries the previous record's hash and a signature over (hash, prev_hash, seq).
• Checkpoints sign the chain head every few records, at every run end and on shutdown, and are published to witnesses outside the attacker's reach.
• Bundles hold a run's records, checkpoints and policy snapshots, and verify offline against a pinned key or a witness.

What a verified bundle proves

tracekit verify ends with two lines; read them together.

• Integrity: the records are the ones the signer signed, with none edited, removed or reordered; the head is covered by a checkpoint; every policy decision is tied to the policy snapshot that made it. It is anchored only if you pass the signer's key (--key) or a witness (--witness).
• Assurance: who could have rewritten the ledger before it was checkpointed. dev means the signer ran as the agent's own user. System mode puts it under a separate OS user.

A verified bundle does not prove intent, complete coverage, or that a reported tool result is real. Anything the agent does outside a capture path (inside a subprocess, after the last hook) is not seen; the verifier lists the blind spots a run touched. Every claim is mapped in the threat model.

Supported today

Linux runs dev mode and system mode; macOS runs dev mode and an experimental system mode; Windows runs dev mode only (platforms). Separate packages under contrib/: proofpack (auditor zip), query (SQL and MCP over the ledger), stagehand, causeway, onchain.

System mode (Linux)

sudo /usr/bin/python3 -m tracekit init --user <agent-user> --witness git:/var/lib/tracekit/witness@git@github.com:you/tk-witness.git
tracekit status

Run init with a root-owned Python. It installs Tracekit into a root-owned virtualenv at /opt/tracekit (the same tracekit-ai version from PyPI, or this repository from a root-owned clone), runs the signer as its own OS user, and blocks tool calls while the signer is down (fail closed). tracekit doctor checks that nothing the agent can modify is on that path. Register the agent CLI as the harness (--harness) and the signer accepts runs only from that program's process tree.

Policy and approvals

Rules live in tracekit/policy/default.yaml: deny blocks the call, ask holds it until someone runs tracekit approve or tracekit reject (outside dev mode, a different OS user), and flag lets it through and marks it. strict.yaml fails closed and asks before pushes, publishes and uploads. Rules are regex tripwires that a determined agent can evade; the guarantees come from the signer, the chain and the witness.

Use in CI

Verify a bundle in a GitHub Actions workflow:

- uses: Cygnux-Labs/Tracekit@main
  with:
    bundle: run.tkb
    key: keys/signer.pub        # pin the signer; or witness: git:/path/to/clone

require-anchor defaults to true, so an unanchored bundle fails the step; set require-anchor: "false" to only report it.

CLI

tracekit --help lists every command. The common ones: init, status, doctor, demo, observe, pending / approve / reject, export, verify (exit 0 ok, 1 fail, 2 unusable bundle, 3 warnings with --strict), analyze, uninstall.

Docs

Threat model · signing · witnesses · privacy · findings · evaluation · review packet

Roadmap

Tracekit is being extended from laptop coding agents to server-hosted agents: a signer service that agents reach over the network, evidence format v2 and policy enforced inside the signer. Existing v1 bundles keep verifying.

Contributing and security

See CONTRIBUTING.md: make install, then make check runs lint, tests and the build. Report vulnerabilities privately as described in SECURITY.md.

Licence

MIT, Copyright Cygnux Labs. See LICENSE.