# halo-record

> Tamper-evident, hash-chained runtime audit logs for AI agents — dependency-free, verifiable by anyone, and designed for compliance evidence.

halo-record is an open-source Python library by Brian Kuan that creates tamper-evident, append-only audit trails for AI agents. Every tool call, model call, data access, and approval an agent makes becomes a hash-chained record that any party can independently verify — without trusting the operator who produced it. The project is licensed under Apache-2.0 and currently in Alpha (Development Status 3), with active releases on PyPI.

## What It Is

halo-record implements the Halo Runtime Record format: a JSONL-based, hash-chained log where each record's integrity is anchored to the previous one using RFC 8785 canonicalization and SHA-256. The package ships a recorder, a conformance verifier, a witness client, and a report server — all in approximately 4,300 lines of pure Python with zero runtime dependencies. The format is open and free to implement; this package is the reference implementation. A TypeScript counterpart (`halo-record-ts`) ships the same chain format and witness protocol for the Node/JS ecosystem.

## How the Integrity Model Works

Each record's hash is computed by taking the record (excluding `integrity.hash`), setting `integrity.prev_hash` to the previous record's hash, canonicalizing with RFC 8785, and SHA-256-ing the bytes. The first record's `prev_hash` is 64 zeros. Verification recomputes every hash and checks every link — no secret required. The library distinguishes between **integrity** (nothing was edited or reordered after the fact, provable by the chain itself) and **completeness** (no records were deleted and re-sealed, which requires an external witness holding periodic chain fingerprints). The `halo anchor` command supports both local and hosted witness workflows.

## Adapter Matrix and Integrations

halo-record connects to a wide range of agent runtimes and telemetry sources without requiring code rewrites:

- **Captured at the boundary:** native `trace()` wrapper, MCP interceptor, LangChain/LangGraph callback, OpenAI Agents SDK hooks, Claude Code/Claude Agent SDK hook
- **Ingested from existing telemetry:** OpenTelemetry GenAI spans (covering CrewAI, LlamaIndex, and most OTel-instrumented frameworks), LiteLLM callbacks, Langfuse export, any gateway/reverse-proxy log

Every record carries a `source` tag so the report discloses how each piece of evidence was collected. Raw argument values never enter a record — arguments are hashed and stored only as a redacted summary.

## Where It Fits in a Compliance Stack

The project positions halo-record as an evidence layer for AI governance frameworks, not a certification tool. The README maps it to several frameworks:

- **SOC 2 / security questionnaires:** verifiable Runtime Reports instead of screenshots and prose
- **OWASP GenAI Security Project / Top 10 for LLM Applications:** runtime evidence for excessive agency, tool misuse, and sensitive-information disclosure
- **AARM (CSA):** produces the tamper-evident action receipt specified in R5/R6
- **EU AI Act:** logging and record-keeping obligations for high-risk AI systems
- **ISO 42001 / NIST AI RMF:** operational evidence behind management-system controls

## Update: Version 0.2.4

The latest release is v0.2.4, published on July 9, 2026, following a rapid release cadence since the project's initial v0.1.0 on June 12, 2026. The 0.2.x series introduced the authority snapshot mechanism (sealing session rules, MCP tool registries, and policy refs into the hash chain), the `halo hook` command for Claude Code's `PostToolUse` hook, and the `halo export` command for date-bounded evidence exports. The project has 52 GitHub stars and 6 forks as of the latest metadata, and the repository shows zero open issues.

## Features
- Append-only, hash-chained audit log for AI agent actions
- Zero runtime dependencies — standard library only
- No network calls except opt-in witness (chain fingerprint only, no record contents)
- Raw inputs never stored — arguments hashed and redacted
- CLI: verify, report, serve, grant, anchor, demo, export, hook
- Self-verifying HTML Runtime Reports per tenant
- Per-customer gated report serving over HTTP
- Completeness witnessing via external anchor checkpoints
- Authority snapshot sealing (rules, MCP registries, policy refs)
- MCP interceptor adapter
- LangChain/LangGraph callback adapter
- OpenAI Agents SDK hooks adapter
- Claude Code PostToolUse hook integration
- OpenTelemetry GenAI spans ingestion
- LiteLLM callbacks ingestion
- Langfuse export ingestion
- TypeScript counterpart (halo-record-ts) with same chain format
- CI-friendly non-zero exit on verification failure
- Date-bounded evidence export (CSV + manifest)
- RFC 8785 JSON Canonicalization Scheme for hash computation

## Integrations
LangChain, LangGraph, OpenAI Agents SDK, Claude Code, Claude Agent SDK, MCP (Model Context Protocol), OpenTelemetry, LiteLLM, Langfuse, CrewAI, LlamaIndex, Vercel AI SDK

## Platforms
WEB, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
0.2.4

## Links
- Website: https://pypi.org/project/halo-record/
- Documentation: https://github.com/bkuan001/halo-record
- Repository: https://github.com/bkuan001/halo-record
- EveryDev.ai: https://www.everydev.ai/tools/halo-record