hhHalfhand

hh export / hh import / hh replay --web

Three ways to move a session off the recording machine:

Goal Command
Machine-readable JSON (jq-friendly) hh export [session]
A portable archive you can hh import elsewhere hh export [session] --bundle -o FILE
A page to share/open in a browser hh export [session] --html -o FILE, or hh replay [session] --web [--open]

All three are redacted by default — see `docs/redaction.md`. --no-redact requires an interactive typed confirmation and is refused on a non-TTY stdin; there is no bypass flag, so a script can never exfiltrate a raw session by accident.

$ hh export last --bundle -o session.hh
✓ Exported session a1b2c3 → session.hh (bundle, redacted)

$ hh import session.hh
✓ Imported session f9e8d7 (from a1b2c3) · 12 steps · hh replay f9e8d7

$ hh replay last --web
✓ Exported session a1b2c3 → ~/.local/share/halfhand/exports/hh-session-a1b2c3.html (html, redacted) — open it in a browser

The bundle format (--bundle)

A .hh file is a single zstd-compressed tar:

manifest.json     format_version, hh_version, the session block, integrity hashes
events.ndjson     one compact JSON object per event, seq-indexed
blobs/<h2>/<hash> raw content for every blob any event or file_change references

Only the outer tar stream is compressed — blobs are stored raw inside it (no double compression). Building it twice from an unchanged session produces byte-identical bytes: tar entries are added in a fixed order (manifest, events, then blobs sorted ascending by hash) with fixed mtime/uid/gid/mode, and the manifest carries no wall-clock field.

manifest.json

{
  "format_version": 1,
  "hh_version": "0.1.0-beta.1 (abc1234)",
  "session": { /* the hh list --json session object, see docs/json.md;
                 an import restores its name, model and usage fields */ },
  "integrity": {
    "events_blake3": "<hex>",       // BLAKE3 of events.ndjson's bytes
    "event_count": 12,
    "blobs": [ { "hash": "<hex>", "size": 481 }, ... ]
  }
}

hh import rejects a bundle whose format_version is newer than the highest version that build of hh understands, with an actionable "upgrade hh" message. Same-or-older versions of format 1 are accepted (the only version that exists today).

events.ndjson

One line per event, in the session's original (ts_ms, id) order. DB row ids don't survive import, so events are addressed by position (seq, 0-based) instead, and correlates becomes correlates_seq:

{
  "seq": 3,
  "ts_ms": 1204,
  "kind": "tool_result",
  "step": 2,
  "correlates_seq": 2,
  "summary": "tool_result: ok",
  "body": { "content": "file.txt", "is_error": false },
  "blob_hash": null,
  "blob_size": null,
  "file_change": null
}

body is exactly as stored — unlike hh inspect --json's event object, it is not blob-overflow-resolved, so a large payload may still carry the {"overflow": true, "blob_hash": "...", ...} envelope; the referenced blob is always present under blobs/ in that case.

Blobs

Every hash any event's blob_hash or file_change.before_hash/after_hash references is packed under blobs/<hash[0..2]>/<hash>, content-addressed and BLAKE3-verified on import. This is the one thing plain hh export (no --bundle) cannot carry: its JSON only ever includes hash references for file changes, never the bytes. A file_change also carries before_source and renamed_from when they were recorded, so hh import re-takes the reference a git/baseline before-side blob holds and hh gc in the importing store keeps it (see Recording).

Redaction and hash remapping

Redaction (when enabled) runs over the session block, every event, and every referenced blob's content — the same chokepoint plain hh export/hh export --html use. If redacting a blob's content changes its hash, every reference to the old hash (the event's blob_hash, a file_change's before_hash/after_hash, or an embedded blob_hash inside an unresolved overflow envelope) is rewritten to the new one before the bundle is built — nothing in the bundle ever points at a hash that isn't in it.

hh import

hh import FILE

Validates the bundle end to end before touching the store: zstd decompression is bounded (defense against a hostile/corrupt frame), every tar entry must match the allow-list above (a symlink/hardlink/unexpected path is refused), every blob's content is BLAKE3-verified against its filename, events.ndjson's digest is checked against the manifest, and every hash any event references must be present among the bundle's blobs. Each failure mode reports precisely what's wrong — not one generic "corrupt bundle" message.

On success, the session is imported under a brand-new local id — the bundle's format_version and content-addressing mean imports are always additive, never overwrite an existing session. The original session id is recorded in the new session's imported_from field (hh list --json / hh inspect --json; see `docs/json.md`) so you can trace where it came from. Blobs are written content-addressed, so importing a bundle whose blobs already exist locally (e.g. re-importing, or two sessions sharing a file snapshot) is a no-op for those blobs.

hh import does not re-run redaction — it trusts the bundle's existing redaction state, whatever hh export produced (redacted by default, or --no-redact if the exporter explicitly confirmed that).

Exit codes

Code Meaning
0 Import succeeded.
1 The file couldn't be read, the bundle failed validation, or the import transaction failed.
2 Usage error (clap).

There is no dedicated "corrupt bundle" exit code in Halfhand's documented contract (0/1/2/3/4, see Exit codes); a corrupt or invalid bundle is a generic 1, by design — this is called out explicitly rather than left as an oversight. hh export exits 3 when the session doesn't exist, and 1 when --no-redact is refused for lack of an interactive confirmation.

The HTML replay page (--html, hh replay --web)

hh export --html (and its sugar, hh replay --web) produce a single self-contained HTML file: inline CSS/JS, zero network requests, no CDN, no telemetry, safe to open from file:// or host anywhere.

  • Header: session id, status, agent kind, command, cwd, and (if applicable) which session it was imported from.
  • Terminal output: a collapsed "terminal output · N KiB" section under the header, expanded with a click (rendered lazily on first open). This is everything the agent wrote to its terminal, in order — for sessions with no structured transcript (any agent other than Claude Code) it is most of the session. ANSI colors and bold/dim/italic/underline become styles; every other escape sequence (cursor movement, window titles, OSC 8 hyperlinks) is stripped, \r progress-bar redraws collapse to their final state, and keystrokes recorded with --record-input are left out. Non-UTF-8 output chunks are not decoded; the summary line reports how many bytes were omitted.
  • Timeline: every other event, clickable. Terminal output chunks are not timeline rows (they are not steps).
  • Detail pane: plain text for text-bearing events, pretty-printed JSON for structured events, and a real diff view for file changes (hunks are precomputed server-side, so the page never implements a diff algorithm).
  • Keyboard nav: j/k (and arrow keys) move the selected step.
  • Theme: dark by default, with a toggle button for light — not tied to the OS prefers-color-scheme.

How the page stays safe

Session content is untrusted input to this page (it's whatever the recorded agent/tool output happened to contain). The whole payload is embedded once, inside a single <script type="application/json" id="hh-data"> tag, with every </>/& replaced by its \uXXXX escape first — that makes a </script> sequence structurally impossible to smuggle in, regardless of content. The page's hand-written JS reads that tag's textContent (never innerHTML), JSON.parses it, and builds every other DOM node with createElement/textContent. Nothing recorded is ever assigned to innerHTML, so nothing recorded can ever be interpreted as markup — a <script> tag or onerror= attribute in a summary, a tool result, a diff line, or terminal output renders as inert text, never as live HTML.

Terminal output gets two more guards: escape sequences are parsed and discarded server-side (none reach the page), and each styled run's CSS class is built from a fixed hh-t-* vocabulary and re-checked by the page against that pattern before use.

Redaction and size budget for terminal output

Terminal output is redacted like everything else on the page — and it is redacted on the joined transcript, so a secret split across two output chunks, or by a color change mid-token, is still caught.

Terminal output is usually the largest part of a session, so the page caps it at 2 MiB by default (the whole page stays within ~5 MiB for a typical session). Past the cap, the page keeps the head and tail of the transcript around a visible … N truncated — raise [export] html_terminal_max_bytes … marker. Truncation happens after redaction, so a cut can never split a secret into halves that escape detection. Raise or remove the cap in config.toml:

[export]
html_terminal_max_bytes = "8MiB"   # or an integer byte count; 0 = no limit

Where the file goes, and --open

Invocation Output
hh replay [session] --web <data_dir>/exports/hh-session-<short_id>.html; path printed on stdout
hh replay [session] --web -o page.html page.html; path printed on stdout
hh replay [session] --web -o - HTML on stdout, nothing else
hh export [session] --html HTML on stdout (unchanged)
hh export [session] --html -o page.html page.html; path printed on stdout
hh export [session] --html -o - HTML on stdout (-o - works for every export format)
hh export [session] --html --open <data_dir>/exports/hh-session-<short_id>.html, then opened

<data_dir> is the Halfhand data directory (HH_DATA_DIR, [storage] data_dir, or the platform default — hh doctor prints it). Pages there are not reaped by the OS like a temp dir; re-exporting a session overwrites its page, and rm -r <data_dir>/exports is always safe.

--open (with --html or --web) opens the page in your default browser (xdg-open on Linux, open on macOS). It is honoured only when stdout is a terminal and the CI environment variable is not set; otherwise the page is still written, the path is printed, and one line on stderr says why no browser opened. If no opener is available (headless Linux, an SSH session), the command still succeeds and prints the path with a one-line hint. --no-open cancels an earlier --open (handy behind a shell alias).

The stdout epilogue line is unchanged — ✓ Exported session <id> → <path> (html, redacted) — so scripts that parse the path after → keep working.

hh replay --web

Sugar for the common "just let me look at this in a browser" case:

hh replay [session] --web [--open] [-o FILE|-]

Builds the same redacted HTML page hh export --html would, writes it to <data_dir>/exports/hh-session-<short_id>.html (earlier versions used $TMPDIR/hh-replay-<short_id>.html, which the OS could delete), and prints the path. Needs no terminal (unlike plain hh replay, which opens the interactive TUI and requires one), and never starts a server. Add --open to launch your browser too (see above).

See also