Recording
hh run wraps a command in a PTY and records what happens.
hh run -- claude # record a Claude Code session (auto-detected)
hh run -- python3 my_agent.py # record any command
hh run -- codex # any other agent: terminal output + file changes
Everything after -- is the command to record.
To record an agent you can't launch through hh — a GUI app, or a session
that is already running — use `hh watch`, which records the
file changes in a directory without wrapping a command.
What gets captured
- Terminal output — ANSI/UTF-8 bytes (and binary chunks) from the PTY.
- File changes — create/modify/delete under the working dir, with BLAKE3 before/after hashes and zstd-compressed contents.
- Agent turns — for Claude Code only, the agent's internal prompts, tool calls and tool results, as structured events. Other agents (including Codex CLI and Gemini CLI) get terminal output and file changes only. See Adapters.
- MCP traffic — when the agent's MCP servers are wrapped in
hh mcp-proxy.
File changes: where the before-side comes from
A diff needs two sides. The after-side of a file change is whatever is on disk when the watcher reads it. The before-side is the content the file had just before the change, and the recorder resolves it in this order:
before_source |
When | Before-side content |
|---|---|---|
live |
The watcher already recorded this path earlier in the session. | That earlier change's after-side. |
git |
The file existed at session start and was clean against the git index. | The index blob, read with git cat-file --filters (same line endings and filters as a checkout) and stored when the file first changes. |
baseline |
The file existed at session start but was dirty, untracked, or outside a git repository. | The file's content, captured when hh run started. |
none |
A created file, or one whose previous content was not captured (see limits below). | None. The diff shows only added lines (or "content not captured" for a delete). |
So a one-line edit to a file that existed before the session shows as one removed and one added line. Deleting a pre-existing file shows the removed content. That holds in a git repository and outside one.
The git-clean rule
Halfhand uses git only for files that were clean against the index when the
session started. It never diffs against HEAD, and it never uses the index
for a file you had already edited. Say you have uncommitted edits to
main.rs, start hh run, and the agent changes one more line. The recorded
diff shows only the agent's line. Diffing against git would show your edits
as well and attribute them to the agent. Dirty and untracked files get a
real snapshot of their content at session start (baseline).
"Clean" means: tracked at stage 0 (not mid-merge), a regular file (not a
symlink or submodule), and not listed by git diff-files. Halfhand never
refreshes or writes your index. If git's stat cache is stale, a file whose
content didn't change can be reported dirty. That only means its content is
captured as a baseline instead. A git before-side is also checked
against the file's session-start content hash and dropped (none) if they
differ, so a smudge filter or a mid-session index rewrite can't put the
wrong text in a diff.
Limits
The same rules apply to before-sides as to live captures:
- Files over
max_file_size(default 4 MiB) are not captured at all. - Binary files (a NUL byte in the first 8 KiB) store no content unless
record_binary = true. - Baseline content (dirty, untracked or non-git files) is held in memory
for the session, up to
[record] baseline_budgetin total (default 32 MiB). Git-clean files don't count against the budget. Files past it record their first change withbefore_source = "none", andhh runprints one note saying how many files that affected. Raise the budget, or commit or stash first, if you need diffs for a large dirty tree. Set it to0to turn baseline capture off.
[record]
baseline_budget = "128MiB" # default: 32MiB; 0 disables baseline capture
Nothing is written to the blob store at session start. A before-side is
stored only when its file actually changes, through the same (redacting,
with [redaction] at_record) blob store as every other capture. Each
git/baseline before-side blob is refcounted by its own file_changes
row, so hh rm and hh gc reclaim it like any other blob, hh scan and
hh redact cover it, and hh export --bundle / hh import carry it.
Renames
A rename is recorded as one change on the new path, with the old path
in renamed_from (hh inspect --json shows it in the event body).
hh inspect --diff prints it the way git does:
diff -- a/old.txt b/new.txt
rename from old.txt
rename to new.txt
A rename that also changed the content is followed by the usual hunks. The two halves of a rename are paired by the OS when it reports them together (Linux inotify, Windows). Otherwise they're paired by identical content within the same debounce window (macOS FSEvents reports each half separately). Empty files are never paired by content. Moving a file onto an existing path is recorded as a modify of the target plus a delete of the source. If the watcher misses both halves (for example, every file inside a renamed directory), the shutdown rescan records them and pairs them by content too.
Flags
--adapter <name>— force an adapter instead of auto-detecting.claude-codeis the supported value.codex-cli,gemini-cliandclaude-desktopare deprecated and scheduled for removal in the next minor release: they still work as before but print a one-line deprecation warning, and the Codex and Gemini adapters never captured structured events. See Adapters.--record-input— also record your keystrokes. Off by default because keystrokes may contain secrets. Enable only when you need to reproduce exact input, and scan/redact before sharing.
Dropped events and the ⚠ marker
Halfhand never drops events silently. If an event cannot be written to the database (a full disk, an I/O error, a read-only data dir), recording keeps going and Halfhand:
prints one warning line to stderr at the first failure, naming what failed and why — not one line per event, so a full disk does not flood your terminal;
counts every event it could not write, and reports the total in the end-of-run summary, with a
⚠instead of✓:⚠ Recorded session a1b2c3 · 4m32s · 42 steps · 7 files changed · 1312 events dropped · hh replay a1b2c3 hh: warning: 1312 events could not be written and are missing from session a1b2c3 (first failure: …) — the session is marked degraded; …marks the session degraded:
hh listandhh inspectshow its status as✓ ok ⚠— the same marker used when the agent adapter degrades — so a session with gaps in its timeline never looks like a cleanok. The count and the first failure's cause are saved with the session (dropped_events/dropped_events_reasoninhh list --json), survivehh export/hh import, and are reported byhh doctor.
The session's status still reflects how the recorded command exited
(ok, error, interrupted); ⚠ means "this recording is incomplete or
less detailed than it should be", for either reason. To find out why, run
hh doctor. It names the cause and the affected sessions; the usual fix is
freeing disk space or fixing permissions on the data dir.
Health check
hh doctor is a read-only probe of the recording stack (PTY, watcher, store).
Run it before a session you suspect is broken, or from CI:
hh doctor
hh doctor --json | jq
See Doctor.
Session status
A session's status (shown by hh list, hh inspect and --json) is one of:
| Status | Meaning |
|---|---|
recording |
The recording is still running. |
ok |
The recorded command exited 0. |
error |
The recorded command exited non-zero. |
interrupted |
The hh process recording the session stopped before finalizing it (it was killed, crashed, or the machine went down). The session is still inspectable up to the last event written. |
How a crashed recording becomes interrupted
When hh run starts, the session records which process is recording it: the
hh process's id and its start time. Every hh command (hh list,
hh inspect, another hh run, …) checks each recording session and marks it
interrupted only when that recorder is gone:
- no process has the recorded id, or
- a process has it, but with a different start time. Process ids are reused, so a crashed recorder's id can later belong to an unrelated program; the start time tells them apart.
So you can run hh list or hh inspect in another terminal while
hh run is recording, and the live session keeps showing recording.
Liveness is checked on Linux (/proc), macOS and Windows. When it cannot be
determined (an unsupported platform, no permission to see the process,
/proc not mounted, or a data dir shared between machines), Halfhand leaves
the session recording rather than risk marking a live recording
interrupted. A session stuck in recording this way is still fully
inspectable. Sessions recorded by Halfhand versions before this check have no
recorder recorded; they are marked interrupted as before.
Exit code
hh run exits with the recorded command's own exit code, so
hh run -- make can stand in for make in a script. That means 2, 3 and
4 from hh run are the command's codes, not Halfhand's usage /
session-not-found / policy codes. A command killed by a signal makes hh run
exit 1, and so does a failure in hh itself before the command starts. See
Exit codes.