Halo Record Agent Audit Trails
Create tamper-evident AI agent audit trails that customers can verify independently.
- Source repo
- bkuan001/halo-record
- Stars
- ★ 86
- Last updated
- 20d ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 82/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code · OpenAI API · Claude API
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- An AI software vendor answering a customer's security team with a verifiable Runtime Report showing how its agent handled customer data.
- Not a fit if
- Teams that need proof every real-world action was captured
- Teams requiring built-in retention, pruning, or complete deletion of chained personal data
- Systems unable to serialize writers or give parallel workers separate chains
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-01latest release v0.2.47 (2026-11-01)
- Source review
- 82/100 · Good
What does this agent do, and when should you use it?
Halo Record is a dependency-free Python reference implementation for hash-chained records of agent runs, tool calls, model calls, data access, and approvals. It includes Recorder, trace, record_call, framework adapters, a verifier, a witness client, a report server, and a CLI, with documented paths for MCP, LangChain/LangGraph, OpenAI Agents SDK, Claude Agent SDK, OpenTelemetry GenAI, LiteLLM, Langfuse, and gateway logs. Records are appended to local JSONL chains and can be rendered as browser-verifiable Runtime Reports or exported as CSV with a manifest tied to the source chain head. Checkpoints held by an external witness can expose rewritten committed history or missing checkpoints, while optional RFC 3161 timestamps establish that a chain state existed no later than an attested time. This is an evidence layer rather than a certification system or enforcement gateway: hashes do not prove every action was captured, and a sealed verification status only preserves what the integration reported. Core recording and verification run locally; networking is limited to explicitly invoked witness and timestamp operations.
At an action boundary, an application uses Recorder, trace(), record_call(), or a framework adapter to seal a canonical input hash, an optional best-effort redacted summary capped at 200 characters, the outcome, subject, provenance, parent link, and optional verification and authority blocks. Each record is canonicalized with RFC 8785, hashed with SHA-256, and connected to its predecessor through integrity.prev_hash; halo verify recomputes the hashes and validates both schema and links. halo report produces self-verifying HTML, halo serve exposes customer-scoped reports, halo export creates a date-bounded CSV and manifest, and halo policy evaluates declarative rules as passes, violations, or evidence gaps. halo anchor sends the subject ID, record count, chain head, and chain root to a local or remote witness and can attach an RFC 3161 time proof; record contents are not included in that request. Existing systems can also feed the format through MCP interception, LangChain callbacks, OpenTelemetry GenAI spans, LiteLLM callbacks, Langfuse exports, gateway logs, and Claude Code or Codex PostToolUse events.
- An AI software vendor answering a customer's security team with a verifiable Runtime Report showing how its agent handled customer data.
- A compliance team preparing date-bounded logging evidence for SOC 2, AIUC-1, AICM, ISO 42001, the EU AI Act, or NIST AI RMF reviews.
- A platform team combining LangChain, LangGraph, MCP, or OpenTelemetry GenAI events into one chain while retaining source provenance.
- An engineering team recording Claude Code or Codex file changes, shell commands, and MCP calls without modifying the coding agent.
- A high-assurance deployment asking a customer or another outside party to retain periodic checkpoints so committed-history rewrites become detectable.
- An audit team exporting only relevant tool calls as CSV plus a verification manifest for upload to a GRC platform such as Vanta or Drata.
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
uvx --from halo-record halo demo --servepip install halo-record
- Config files
~/.claude/settings.json~/.codex/hooks.json~/.halo/audit.jsonl
How do you install or deploy this agent?
The local demo requires no agent, account, or API credential. With uv, run the package directly:
uvx --from halo-record halo demo --serveAlternatively, install it with pip and start the demo:
pip install halo-record
halo demo --serveThe demo creates a fictional vendor with two customers, checkpoints the chains to a local witness file, serves their Runtime Reports, and opens the operator console. The Apache-2.0 package is usable for free; networking is needed only if you explicitly choose a remote witness or RFC 3161 timestamp service.
How do you use this agent?
Wrap a Python agent entry point to record the run boundary:
from halo_record import trace
agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl")Capturing individual tool calls requires record_call() at each boundary or a supported adapter:
from halo_record import Recorder, record_call
rec = Recorder("audit.jsonl")
with record_call(rec, "crm.lookup", {"account": "acct-9"}) as call:
call.result = crm.lookup("acct-9")
with record_call(rec, "payments.refund", {"amount": 120},
parent_id=rec.last_record_id()) as call:
call.result = payments.refund(120)Verify the chain and render a report:
halo verify audit.jsonl
halo report audit.jsonl -o report.htmlTo serve customer-scoped reports from a records directory, run:
halo serve ./records --port 8721For Claude Code, add this to ~/.claude/settings.json:
{
"hooks": {
"PostToolUse": [
{"matcher": "*", "hooks": [{"type": "command", "command": "halo hook"}]}
]
}
}For Codex, add this to ~/.codex/hooks.json:
{
"hooks": {
"PostToolUse": [
{"matcher": ".*", "hooks": [{"type": "command", "command": "halo hook"}]}
]
}
}Both hook configurations write to ~/.halo/audit.jsonl by default. HALO_LOG changes the destination, and HALO_HASH_ONLY=1 disables summaries. To commit history to a witness and check it later, run:
halo anchor audit.jsonl witness.jsonl
halo anchor audit.jsonl witness.jsonl --checkWhat are this agent's strengths and limitations?
- The runtime uses only the Python standard library; core recording and local verification need no external service or network.
- An open format, RFC 8785 canonicalization, and SHA-256 chaining let third parties implement independent verification without a secret key.
- It supports both boundary capture and telemetry ingestion, with a
sourcetag disclosing how each piece of evidence was collected. - External checkpoints strengthen historical integrity, and optional RFC 3161 proofs add independently verifiable time without sending record contents.
- Outputs cover self-verifying HTML, policy findings, and CSV evidence with both a source-chain head and an export-file hash.
- The documentation explicitly separates record integrity, capture completeness, and trusted capture instead of presenting a hash chain as universal proof.
- A self-held chain only detects edits relative to a previously established head; before an outside party sees a head, the operator can remove records and reseal.
- No hash chain proves that every real action passed through the recorder; completeness still depends on instrumentation placement and the capture boundary.
- Redaction is best-effort regex and entropy detection, so names, postal addresses, and free-form sensitive text may become permanent chain content.
- There is no built-in retention or pruning; deleting chained records breaks subsequent verification, so personal-data handling requires external pseudonymous mappings.
- Chains require single-writer semantics; parallel writers bypassing
Recorderneed an equivalent lock or separate per-process chains. - Framework callbacks fail open by default, allowing an action to complete when evidence cannot be written; only checkpoint cadence can reveal a stalled chain.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Halo Record Agent Audit Trails This agent | 82 · Good | CLIFree | ★ 86 | 20d ago | Python | Codex · Claude Code · OpenAI API · Claude API |
| OpenInference | 66 · Some gaps | Library / SDKFree | ★ 1.3k | today | Python | OpenAI API · Claude API |
| Prismor | 61 · Some gaps | CLIFree + model costs | ★ 583 | today | Python | Codex · Claude Code · OpenAI API · Claude API |
| Cordum Agent Control Plane | 75 · Some gaps | Self-hosted serviceFree | ★ 507 | 3d ago | Go | Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The package declares no runtime dependencies, defines recording and network boundaries, and documents pass-through versus strict recording failure behavior, supporting strong least-privilege and dependency-security scores. Optional network operations require invocation, but the packet does not show interactive confirmation for each sensitive action, so user confirmation earns only partial credit. README and SECURITY explain record contents, redaction limits, outbound exceptions, and write failures. Redaction is best-effort and short unmatched text can remain in summaries, so sensitive-data handling is not full marks. Optional witnessing, timestamping, and email have external effects; recovery or correction procedures for recorded data are not well evidenced. The project name, author, and security email support attribution, while maintenance responsibility and update commitments remain limited.
README, CLI, and test material describe empty chains, witness completeness, failed writes, strict mode, and async wrappers in specific, mutually consistent terms, supporting high static self-consistency and failure-message scores. The project declares zero runtime dependencies and specifies Python versions, but examples also rely on optional ecosystems and external services, so dependency availability earns partial credit. No runtime outcome is inferred.
The packet covers native recording, multiple framework adapters, MCP, telemetry ingestion, gateways, coding-agent hooks, and buyer-side platform logs. It distinguishes captured from ingested evidence and explains what integrity and completeness claims cannot establish; hook triggers and capture boundaries are also described concretely. Environment fit receives partial credit because the material centers on Python/CLI and specified hook environments, and some integrations involve external components.
The README is organized by use case and includes installation, quick starts, code examples, failure handling, and separate limits, privacy, and retention documents. Information architecture, install notes, examples, and known limitations are strong. The LICENSE and package metadata both identify Apache-2.0. A `halo` import-name collision is documented with a workaround, but it still reduces naming stability. The package version is 0.2.47, while the supplied material does not include changelog content. An author, security contact, and issue entry point are present, but ongoing maintenance responsibility is not detailed.
The product emits shareable HTML reports and JSONL chains that can be checked in the browser or through the CLI. This gives outside reviewers a clear usable output, and the distinctions among hash chains, external checkpoints, and capture boundaries provide concrete audit value. Cost-benefit earns partial credit: the core is dependency-light and the demo is accessible, but production evidence quality depends on correct capture placement, external witnessing, and operational configuration.
The main security and integrity claims are traceable to README references to LIMITS/PRIVACY/SECURITY, CLI behavior, and supplied test source; CI configuration also documents automated tests and sample-chain verification. The sources corroborate recording-failure behavior, witnessing, and verification boundaries. Documentation separates what record fields report from what Halo can prove, and discloses fictional demo data and limits around uncaptured actions. Static verifiability therefore earns high marks; this assessment did not execute code or tests.
- Redaction is best-effort; short arguments that match no known pattern may remain verbatim in summaries. Use `summaries=False` for sensitive inputs and avoid recording free text or private policy content.
- A hash chain alone cannot prove completeness or that every action was captured. Use checkpoints held outside the operator and place the recorder where the agent cannot disable it. Recording happens after the action, so retrying after a strict-mode error may repeat external side effects.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.2.47 0.2.47
Release notes excerpt
Release 0.2.47 Buyer-side door. halo door reads a platform log export the buyer already holds (a GitHub security log, or Salesforce Event Monitoring CSVs including Agentforce actions and callouts), seals it on ingest, and renders a page of what one outside agent did: the actions, the credentials used, where it reached, which rules broke, and what the export cannot show. The page re-verifies the embedded chain in the browser and withholds its summary, narrative, and rules when verification fails. Two synthetic sample exports ship in the package; halo door --sample runs …View on GitHub ↗ -
v0.2.46 halo-record 0.2.46
Release notes excerpt
halo-record 0.2.46 A security and evidence-integrity release. Upgrading is recommended for everyone; read the upgrade notes if you run halo serve. Security - Tenant isolation: per-subject chain files with digest-suffixed names; grants and share links are keyed by subject id; halo grant refuses names whose report halo serve would withhold; grants from 0.2.45 are carried only when unambiguous and otherwise quarantined and printed at startup. …View on GitHub ↗ -
Release notes excerpt
- The IBAN matcher is built from 4-character blocks and, when a match runs past the account number into the words that follow it, retries shorter endpoints before giving up — so "DE89 … 00 today" and "…013000EUR" mask whole instead of passing through unmasked. Tab, non-breaking-space, and double-space separators are accepted; a card match inside an accepted IBAN no longer co-classifies it. The api_key pattern accepts underscore and hyphen segments (sk-ant-…). …View on GitHub ↗
FAQ
Does local use require a paid service or model API key?
Can it prove that every agent action was recorded?
What happens if recording fails?
trace() wrapper fails closed, so a write exception propagates into the action. Framework adapters such as the LangChain handler fail open: the action continues, while a warning and loss counter report the missing evidence.Are tool arguments or customer records sent to a witness?
Can several worker processes append to one chain?
Recorder provides a sidecar lock; direct writers must implement an equivalent lock or write separate chains.Is Halo Record Agent Audit Trails open source?
Is Halo Record Agent Audit Trails safe to use?
Is Halo Record Agent Audit Trails still maintained?
Who makes Halo Record Agent Audit Trails?
Thanks — we use this to improve the page.