Tracekit Agent Audit and Policy Guard
Check tool calls before execution and produce signed run records that can be verified offline.
- Source repo
- Cygnux-Labs/Tracekit
- Stars
- ★ 150
- Last updated
- today
- License
- MIT
- Primary language
- Python
- FA score
- 82/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformClaude CodeCodex · OpenAI API (Partial support)
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A team whose agents run shell commands, edit files, or query databases can check risky calls before they execute and preserve the decisions.
- Not a fit if
- Teams that only need post-run debugging traces
- Teams that need records of actions outside the capture path
- Source review
- 82/100 · Good
What does this agent do, and when should you use it?
Tracekit adds policy checks, signed records, and run review to AI agents' tool calls. Python agents can integrate with tracekit.instrument(), with additional paths through the TypeScript SDK, CLI hooks, and gateways. Calls can be allowed, denied, or held for human approval; the signer writes calls, decisions, and results into a per-run hash chain. Runs can be exported as .tkb files and verified offline against pinned trust keys. In dev mode, the signer shares the agent's user boundary; the docs also describe isolated deployment under a separate user, in a container, or remotely.
After tracekit.instrument() is added to an agent, Tracekit checks tool names and arguments against policy before execution and allows, denies, or holds each call; held calls can be approved from the CLI, with approval bound to the exact arguments and usable once. The signer signs calls, decisions, and results into that run's hash chain. Control and recording apply to calls that pass through a Tracekit integration. Export evidence with tracekit export --v2 --run ID -o run.tkb, then verify it offline with tracekit verify run.tkb --trust trust.json. tracekit view shows runs, blocked and held calls, approvals, gaps, and replay information. Experimental features include witnesses, cross-checking, containment, and analysis.
- A team whose agents run shell commands, edit files, or query databases can check risky calls before they execute and preserve the decisions.
- An operations team can hold emails, payments, or cloud commands for human review and approve the exact proposed arguments.
- A team that must provide customers or auditors with verifiable run evidence can export
.tkbbundles for offline checking. - Developers using LangChain, LangGraph, the OpenAI Agents SDK, or MCP can add tool-call policy checks and records through documented integrations.
- A team maintaining Claude Code agents can configure hooks to capture and review each run.
How do you install or deploy this agent?
Install the Python package and run the demo; its scripted agent needs no API key. The package supports Python 3.9–3.13, while framework integrations require Python 3.10 or newer.
pip install tracekit-ai
tracekit demo --serverOr run it with uvx:
uvx --from tracekit-ai tracekit demo --serverThe TypeScript SDK requires Node.js 18 or newer:
npm install @cygnuxlabs/tracekit
npx @cygnuxlabs/tracekit upHow do you use this agent?
Put tracekit.instrument() at the start of a Python agent, then run the agent as usual. It starts or reuses a dev signer and instruments the frameworks it finds. Export and verify the latest run with the CLI:
import tracekit
tracekit.instrument()tracekit last
tracekit view --devWire up Claude Code hooks and a dev signer with:
tracekit init --dev --v2Codex, Cursor, Gemini CLI, and OpenCode can be selected with --agent, but those integrations are marked experimental. To verify a bundle offline:
tracekit verify run.tkb --trust trust.jsonWhat are this agent's strengths and limitations?
- The signed hash chain supports offline verification and detects edits, deletions, swaps, and inserted records at the affected record.
- Policies can allow, deny, or hold calls before execution; held-call approvals are bound to exact arguments and used once.
- Python and TypeScript verifiers are available, with integrations for multiple agent frameworks and MCP.
- In dev mode the signer shares the agent's user account, so code running as that user may access the key and re-sign records.
- Actions that bypass Tracekit and are not covered by an imported sensor are neither blocked nor recorded.
- Policy rules match tool names and text, so commands can be reworded; the README describes these rules as tripwires, not a sandbox.
- Witnessing, cross-checking, containment, and analysis include experimental features; isolating the signer requires additional deployment configuration.
How does this agent compare with similar options?
Tracekit presents itself as a complement to tracers such as OpenTelemetry, Langfuse, and LangSmith: those are suitable for debugging, while Tracekit focuses on records that can be checked by someone who does not trust the agent. The README also compares it with guardrail libraries and other tamper-evident logs.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Tracekit Agent Audit and Policy Guard This agent | 82 · Good | CLIFree | ★ 150 | today | Python | Claude Code |
| Cordum Agent Control Plane | 64 · Some gaps | Self-hosted serviceFree | ★ 511 | 3d ago | Go | Claude Code |
| OpenBot: AI Coworkers You Can Trust with Real Work | 57 · Major gaps | Self-hosted serviceFree + model costs | ★ 7k | today | TypeScript | — |
| Vessel Browser | 58 · Major gaps | Desktop appFreemium | ★ 137 | 1mo ago | TypeScript | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
The repository describes a separate signer, per-call policy checks, and human approvals bound to exact arguments and consumed once, alongside deployment permissions and capture boundaries. This supports strong least-privilege and confirmation design, but the README's quick start defaults to a same-user dev signer, which the docs say an agent can reach along with its key. Arguments are recorded as commitments; the docs disclose that timing, sizes, and counts still leak, and redaction is pattern-based, so sensitive-data handling is explained but incomplete. Dependencies have lower bounds and optional extras; CI pins action revisions, scans the container for high and critical issues, and release provenance is described. No dependency lock or audit result is in the supplied material, so dependency security is only partly established. Policy checks and approvals gate calls, but allowed calls can have external effects, text matching can be evaded, and protection depends on using the capture path. Witnesses can detect rollback, with explicit limitations when none is configured; general recovery evidence is thin. A private vulnerability channel and disclosure timeline are documented, but publisher identity is unverified, so source attribution rests only on repository claims.
The README, security model, and security policy agree on integrity, capture coverage, operator power, and limitations without witnesses. CI describes a broad test process, but this assessment did not execute it. Dependencies are broad; core dependencies have some fallback notes, but installing RE2 may require a source build when no wheel exists, so availability is not fully established. Refusal responses, verification failures, and viewer errors have concrete behavior described, but the supplied material does not establish consistent actionable diagnostics for every failure case.
The material addresses developers, auditors, server deployments, and multiple agent frameworks, and distinguishes stable from experimental integrations. It states which actions may escape capture and what the record cannot prove. Applicability is limited by text and tool-name matching and by varying integration maturity, so trigger precision and environment fit receive partial scores; for example, Codex hooks are experimental and system-mode platform support is limited.
The README has clear sections for quick start, capabilities, limits, evidence, deployment, and contribution, with install commands, examples, FAQ links, and explicit limitations. The MIT license file matches package metadata. Package and command names are clear, but the Python distribution name conflicts with an unrelated PyPI `tracekit`, and support tiers coexist with multiple version lines, reducing naming stability. SECURITY.md describes supported versions and a fix path, but the supplied material does not include the full changelog, leaving version history only partly evidenced. Vulnerability reporting is specified, while maintenance responsibility is represented by project and author fields whose publisher identity is unverified.
The signed chain, offline verification, policy decisions, and approval records produce a usable `.tkb` evidence file; the docs include CLI output and review boundaries. Combining record integrity with call control offers clear value. However, text rules can miss rewritten commands, actions outside the capture path are not blocked, and stronger assurance requires separately deploying a signer and witnesses, so the cost-benefit case is not complete for every use.
The README is supported by specific experiment IDs, test names, configuration examples, and limitations in the security model, checklist, integration docs, and CI configuration. These sources corroborate one another within the project but are not independent external validation, and the threat models have not been externally reviewed. The docs distinguish recorded facts, product claims, experiment results, and what cannot be inferred, and disclose synthetic test sets and sample-size limits.
- Same-user dev mode does not protect against an agent with access to that user's environment. Stronger assurance requires isolating the signer from the agent and configuring an independent witness.
- Policy rules match text and tool names; actions outside the capture path are not blocked. Record integrity does not prove intent, result truth, or complete coverage.
- Experiments are project-authored and limited in scale, threat models have not had external review, and Codex hooks and several integrations remain experimental.
FAQ
Does the demo require a paid model or API key?
tracekit demo --server uses a scripted agent and needs no API key. Credentials for a connected agent depend on the model service that agent uses.Can Tracekit prove that every agent action was captured?
Does dev mode prevent an agent from tampering with its records?
How can an external reviewer verify a run?
.tkb bundle and provide a trusted public key or trust file. The verifier checks it offline; the repository also provides a browser verifier that runs locally.