Replay & Inspect
hh replay — faithful playback
hh replay last # interactive TUI on the most recent session
hh replay a1b2c3 # by id
hh replay last --web # write a self-contained HTML page and print its path
hh replay last --web --open # …and open it in your default browser
hh replay last --web -o - # write the HTML to stdout instead
The TUI shows a step timeline alongside a detail pane (message text, tool
calls and results, unified diffs for file changes). --web exports the same
content as a single offline HTML file — including the session's terminal
output, in a collapsed section under the header (colors kept, other escape
sequences stripped, redacted, capped at 2 MiB by default with a visible
truncation marker). No terminal or server is needed. The file is written to
<data_dir>/exports/hh-session-<id>.html (or -o FILE) and its path is
printed on stdout. --open launches your browser only when stdout is a
terminal and CI is unset; if no opener exists (headless, SSH) the path is
still printed and the command still succeeds. See
`docs/export-import.md`
for the safety model, size cap, and destinations.
The replay TUI
a1b2c3 auth refactor ✓ ok
model Claude Opus 4.8 provider Anthropic duration 1m15s steps 10
tokens 51,540 est. cost $0.05 capture transcript · claude-code files 4
────────────────────────────────────────────────────────────────────────────────────────────────────
┌ Timeline · 2/10 ──────────────────────────┐┌ Step 2 · TOOL · 4.0s ───────────────────────────────┐
│00:00 USER 1.0s add token auth to log││✗ failed · latency 3.2s │
│00:01 ✗ TOOL 4.0s tool_call: Bash ││ │
│00:05 AGENT 1.0s I'll add a token para││TOOL — tool_call: Bash │
│00:06 ● FILE 1m00s modified src/auth.rs ││{ │
│01:06 ● FILE 1.0s created README.md ││ "input": { │
│01:07 FILE 1.0s renamed src/mod.rs ││ "command": "cargo test" │
│01:08 FILE 1.0s modified Cargo.toml ││ }, │
│01:09 FILE 1.0s modified src/auth.rs ││ "name": "Bash" │
│01:10 ✗ ERR 2.0s error: rate limited ││} │
└───────────────────────────────────────────┘└─────────────────────────────────────────────────────┘
↵ open · n next moment · f files ? help
The header is always visible: session name, model, provider, wall-clock
duration, step count, token usage, estimated list-price cost, capture tier
and adapter, and files changed. A value Halfhand does not know prints as —,
never as 0 (see the dash convention).
Capture gaps are stated, not hidden. When a session has no structured
transcript events (PTY and file-system capture only), the header says
⚠ no transcript — terminal and file capture only; a
`hh watch` session says
⚠ watched directory — file changes only, no terminal or transcript. A degraded adapter
(⚠ transcript adapter degraded (<reason>)) and events the recorder could not
write (⚠ 12 events not recorded) are shown the same way.
The timeline shows each step's offset from the session start, its kind,
and how long it took — until the next step starts, or for the last step,
until the last agent event or the session end. A duration Halfhand cannot
know is —. The slowest steps (the top tenth, and never under one second)
are drawn in the accent colour, so a slow step stands out. The mark column
shows ✗ for an error or a failed tool call and ● for the slowest step
and the largest diff.
Diffs. Selecting a file change shows a unified diff with old and new line
numbers, the path, and a summary such as modified · +2 −2 · before from the git index. The summary names where the before-side came from (earlier in the
session, the git index, or the session-start snapshot). If the before-side
was never captured, the view says before content not captured and shows the
file as it was after the change, without + marks: marking every line as
added would claim the agent wrote all of it. A rename is titled
old/path → new/path. Binary files say so instead of diffing. Press
Enter to read a diff full width.
Files touched (f) lists every file the session changed with its edit
count, and notes files that were created, deleted, renamed or binary. The
detail pane previews the selected file's latest change. Enter narrows the
timeline to that file's changes, so d steps through its diffs; Esc
returns to the list.
Moments (n / N) cycle through what is worth seeing in a long
session: every error, every failed tool call, the slowest step, and the
largest diff (the file change with the most added and removed lines). The
status line says which moment you are on (moment 2/4 · slowest step · 1m00s · modified src/auth.rs). If a filter hides a moment, the filter is cleared to show it.
The status line shows the three keys that matter in the current view; ?
lists them all.
Keybindings
| Key | Action |
|---|---|
j / ↓ |
Next step. With the detail pane focused or full width, scroll down. |
k / ↑ |
Previous step, or scroll up. |
g / Home |
First step (or top of the detail pane). |
G / End |
Last step. |
PgUp / PgDn |
Page the list or the detail pane. |
Tab |
Switch focus between the list and the detail pane. |
n / N |
Next / previous moment: errors, failed tool calls, the slowest step, the largest diff. |
d / D |
Next / previous file change. |
/ |
Filter steps by kind (tool, file, err, …) or summary text. Enter keeps the filter, Esc clears it. |
J |
Jump to a time offset (mm:ss or hh:mm:ss). |
Enter |
Open the selected step full width; in files touched, open the file's changes. Press again to return. |
f |
Files touched. |
t |
Show or hide terminal output between steps. |
Esc |
Back: leave full width, leave a file's changes, clear the filter, or cancel a prompt. |
? |
Show every keybinding. Any key closes it. |
q |
Quit. |
Colour and themes
The TUI uses one accent colour (cyan on dark terminals, blue on light ones)
for focus, titles, slow steps and moment marks. The only other colours carry
meaning: red for errors and removed lines, green for added lines. Set the
palette with [replay] theme = "dark" | "light" | "auto" in your config;
auto follows the COLORFGBG hint your terminal may export and otherwise
uses dark. With NO_COLOR set, the TUI uses no colour at all, only bold,
dim, reverse video and strikethrough for removed lines.
hh replay needs an interactive terminal. With stdout piped or redirected it
exits with an error that points you to hh inspect (or use hh replay --web).
Large sessions stay responsive: the timeline keeps only a one-line index per
event in memory, and a frame loads just the selected step's content.
What "faithful" means (and where it ends)
Faithful playback is a transcript, not a re-execution. hh replay shows
what the agent did and said, in order, with the exact tool inputs/outputs and
file diffs it produced. It does not re-run the agent, re-issue tool calls,
or reproduce side effects on your filesystem. Anything the agent did outside
the recorded stream (e.g. a tool with effects Halfhand can't capture) won't be
reproduced — it will only appear as the recorded tool result.
hh inspect — non-interactive detail
hh inspect last # summary + step table
hh inspect a1b2c3 --step 7 # full detail of step 7
hh inspect last --json | jq # stable JSON (single object with --step)
hh inspect last --diff # concatenated unified diff of file changes
hh inspect last --failed # jump to the first error/failed step
hh inspect last --context # model, provider, tokens, durations, cost
The summary header shows the session's name (if any) and, when the transcript
reported one, every model the session used with its step range. The step
table's ELAPSED column is the time from each step to the next (the last step
runs to the last agent event). --context prints the session context panel —
see Session context.
Name a session when you record it, or later:
hh run --name "auth refactor" -- claude
hh rename last "auth refactor, take 2"
hh rename a1b2c3 --clear
The --json shape is documented and frozen as of 1.0 (additive-only); see
JSON reference and the Stability policy.
hh list — every recording
hh list # newest first, default 20
hh list --limit 50
hh list --json