Halo Record Agent Audit Trails

Create tamper-evident AI agent audit trails that customers can verify independently.

Stars
★ 86
Last updated
20d ago
License
Apache-2.0
Primary language
Python

At a glance

How it runs
CLILibrary / SDKSelf-hosted service
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
Pythonpip or uvShell / CLILocal filesystem
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.

  1. An AI software vendor answering a customer's security team with a verifiable Runtime Report showing how its agent handled customer data.
  2. 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.
  3. A platform team combining LangChain, LangGraph, MCP, or OpenTelemetry GenAI events into one chain while retaining source provenance.
  4. An engineering team recording Claude Code or Codex file changes, shell commands, and MCP calls without modifying the coding agent.
  5. A high-assurance deployment asking a customer or another outside party to retain periodic checkpoints so committed-history rewrites become detectable.
  6. 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 --serve
  • pip 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 --serve

Alternatively, install it with pip and start the demo:

pip install halo-record
halo demo --serve

The 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.html

To serve customer-scoped reports from a records directory, run:

halo serve ./records --port 8721

For 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 --check

What are this agent's strengths and limitations?

Pros
  • 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 source tag 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.
Limitations
  • 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 Recorder need 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?

FollowAgents source review · FARS-2.1
Good
82/ 100 5-point scale 4.1 / 5
Trust 19/29
Reliability 12/14
Adaptability 16/18
Convention 15/18
Effectiveness 12/13
Verifiability 8/8
Why each dimension lost points
Trust19 / 29 · 3.3/5

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.

Reliability12 / 14 · 4.3/5

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.

Adaptability16 / 18 · 4.4/5

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.

Convention15 / 18 · 4.2/5

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.

Effectiveness12 / 13 · 4.6/5

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.

Verifiability8 / 8 · 5.0/5

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.

Risks and how to mitigate them
  • 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.
Evidence confidence: Low Reviewed Nov 08, 2026 Reviewed revision 2b3b355f03a3
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/halo-record.svg)](https://followagents.com/en/agents/halo-record)
<a href="https://followagents.com/en/agents/halo-record"><img src="https://followagents.com/badge/halo-record.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. 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 ↗
  2. 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 ↗
  3. v0.2.45
    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?
No. The Apache-2.0 software can demo, record, verify, report, and witness locally without an API credential. Remote witnesses and RFC 3161 timestamps are optional network operations.
Can it prove that every agent action was recorded?
No. The chain proves integrity relative to an established head, and external checkpoints can expose rewrites of committed history. Capture completeness remains a property of where and how the recorder is integrated.
What happens if recording fails?
The native 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?
No. A witness receives only the subject ID, record count, chain head, and chain root; an RFC 3161 authority receives only a checkpoint state hash. Local summaries still require care because redaction is not guaranteed.
Can several worker processes append to one chain?
Only if the entire read-head-and-append sequence is protected by an exclusive lock. Recorder provides a sidecar lock; direct writers must implement an equivalent lock or write separate chains.
Is Halo Record Agent Audit Trails open source?
Yes. The source code is on GitHub (bkuan001/halo-record) under the Apache-2.0 licence.
Is Halo Record Agent Audit Trails safe to use?
FollowAgents' FARS review (Nov 08, 2026) scored Halo Record Agent Audit Trails 19/29 on trust and safety. None of the eight safety controls the review checks for was missing outright.
Is Halo Record Agent Audit Trails still maintained?
Yes. The latest commit on GitHub is from 2026-11-01, within the last 30 days. The latest release is v0.2.47 (2026-11-01).
Who makes Halo Record Agent Audit Trails?
Halo Record Agent Audit Trails is published on GitHub by the account bkuan001. FollowAgents has not verified which person or company is behind that account.
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts