>_OBSERVABILITY

Tamper-Proof Observability

Every agent action, recorded and provable

Wrap any AI agent CLI. Record every event — thoughts, tool calls, file edits, token counts, costs — into tamper-proof NucleusDB traces. Every trace event is a content-addressed blob with a SHA-512 Merkle proof. If any event is modified after the fact, the proof chain breaks.

$ record

agenthalo run claude -p "explain this function" --allowedTools ""

Zero config. Zero telemetry. Nothing leaves your machine.

>_HOW.IT.WORKS

Recording Pipeline

Detect Agent Type

Identifies Claude, Codex, or Gemini from the command name

Inject Output Flags

Adds structured output flags automatically (unless already present)

Spawn & Tee

Agent runs as subprocess — you see everything in real time

Parse Events

Structured output stream parsed into typed trace events

Record to NucleusDB

Events stored as content-addressed blobs with Merkle proofs

Signal Forwarding

SIGINT/SIGTERM forwarded to child process for clean shutdown

>_SUPPORTED.AGENTS

Supported Agent CLIs

Auto-injects the right flags for structured output. If you already pass these flags, AgentHALO won't duplicate them.

Agent	Flags Injected	Purpose
Claude Code	--output-format stream-json --verbose	NDJSON event stream
Codex	--json	JSON output mode
Gemini CLI	--output-format stream-json	NDJSON event stream

agenthalo run claude ...

Record a Claude Code session

agenthalo run codex ...

Record a Codex session

agenthalo run gemini ...

Record a Gemini CLI session

>_TRACE.SCHEMA

Trace Event Types

Thought

Internal reasoning and planning text

ToolCall

Tool name, arguments, and result

FileEdit

Path, old content hash, new content hash

Message

User/assistant message exchange

TokenUsage

Input/output/cache tokens per turn

CostEvent

Per-turn dollar cost with pricing model

Error

Runtime errors and tool failures

SessionStart

Agent type, model, working directory

SessionEnd

Total tokens, cost, duration, exit code

>_COST.TRACKING

Precise Cost Tracking

Per-Turn Tracking

Every API turn records input tokens, output tokens, cache tokens, and computed cost using the pricing table.

Session Rollup

Aggregate cost per session with model breakdown. See exactly what each agent run cost.

Monthly Dashboard

Daily and per-agent cost charts. Identify spending patterns and optimize model selection.

Multi-Model Pricing

Built-in pricing tables for Claude, GPT-4, Gemini, Codex, and local models. Custom pricing support.

>_SHELL.WRAP

Shell Wrapping

Add to your shell profile and every agent invocation is automatically recorded. No behavior change required.

~/.bashrc or ~/.zshrc

eval "$(agenthalo shell-wrap)"

Creates shell functions that transparently wrap claude, codex, and gemini commands.

>_INSPECT

Inspecting Traces

Query recorded sessions from the CLI or the web dashboard.

agenthalo sessions

List all recorded sessions

agenthalo inspect <session_id>

View full trace timeline

agenthalo costs

Cost summary across sessions

agenthalo export <session_id>

Export trace as JSON

Start Recording Your Agent Sessions

One command to install. Zero config. Every action provable.

Install AgentHALO →See the Dashboard