Adapters
An adapter teaches Halfhand how to parse a specific agent's transcript
into structured events (prompts, tool calls, tool results). When you
hh run -- <cmd>, Halfhand auto-detects the adapter from the command.
Every hh run records terminal output and file changes, whatever the
command and whether or not an adapter works for it. An adapter only adds
the structured breakdown on top. An agent without a working adapter is still
recorded, replayable, inspectable and searchable — you just get the PTY output
and file changes, not the parsed agent turns.
Support matrix
| Agent | Adapter | Detect from | Structured events | Verified |
|---|---|---|---|---|
| Claude Code | claude-code |
claude |
Yes — prompts, tool calls, tool results, model and usage | Verified 2026-11-02 |
| OpenAI Codex CLI | codex-cli |
codex |
No — not working. Deprecated | No |
| Google Gemini CLI | gemini-cli |
gemini |
No — not working. Deprecated | No |
| Claude Desktop (Code tab) | claude-desktop |
--adapter claude-desktop only |
Unverified. Deprecated | No |
"Verified" means checked against the agent's real current transcript format on the date shown. Anything else records terminal output and file changes only, or is not something we can vouch for.
Codex CLI and Gemini CLI: not working
The Codex CLI and Gemini CLI adapters have never captured structured events.
Each one finds its agent's transcript (~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl,
~/.gemini/tmp/<hash>/chats/session-*.jsonl) but then parses it with the
Claude Code parser, which does not understand either format. A real Codex
or Gemini session converts zero records, so the session ends with
adapter_status = degraded and a schema-drift reason
(jsonl_schema_drift), and hh prints one adapter degraded warning when
the command exits.
The terminal output and file changes of those sessions are recorded in full. That is the supported way to record Codex CLI and Gemini CLI today.
Earlier README and docs versions listed both as supported. That was wrong.
Deprecated flags
These hh run flags are deprecated and scheduled for removal in the next
minor release (see the Stability policy: a deprecation
warning ships for at least one minor release before anything is removed).
| Flag | Why |
|---|---|
--adapter codex-cli |
The Codex adapter never converted a real transcript (above). |
--adapter gemini-cli |
The Gemini adapter never converted a real transcript (above). |
--adapter claude-desktop |
Desktop capture has not been verified end-to-end. |
Until removal each flag keeps working exactly as before and prints one
line to stderr when hh run starts, in the standard deprecation format:
hh: warning: `--adapter codex-cli` is deprecated; ...
What to do instead: drop the flag. hh run -- codex and hh run -- gemini
still record terminal output and file changes; for the Claude Code agent
inside Claude Desktop, run hh run -- claude in a terminal instead.
--adapter claude-code is not deprecated. Auto-detection is unchanged:
hh run -- codex and hh run -- gemini still select their adapter (and still
degrade, as above) without a warning, because no flag was passed.
Recording a Claude Desktop session (deprecated)
--adapter claude-desktopis deprecated and scheduled for removal in the next minor release (see Deprecated flags). It works as described below until then.
Claude Desktop is a GUI app, so there is no command for hh run to wrap and
nothing to auto-detect from argv. Instead, hh run --adapter claude-desktop
records for as long as the wrapped command runs and, in parallel, finds the
Desktop Code-tab session open in the current directory and tails its
transcript. Wrap a shell and exit it when you are done:
cd ~/proj
hh run --adapter claude-desktop -- $SHELL # or: -- sleep 3600
# ... work in Claude Desktop's Code tab, in ~/proj ...
exit # ends the recording
hh inspect last
Start the Desktop session (or send it a prompt) while the recording is
running: the adapter looks for a session that is new since hh run started
or active after it. An idle session that was opened earlier and never touched
again is not picked up.
How the transcript is found
Desktop's Code tab embeds a Claude Code CLI, so the transcript is the same
JSONL Claude Code writes, in the same place — hh reuses the Claude Code
parser unchanged. What differs is discovery:
- Desktop's session index (primary). Desktop writes one
local_<uuid>.jsonper session under its config directory, carrying the session'scwdand thecliSessionIdthat names the transcript file. The adapter matches the index record for the current directory (skipping archived and deleted sessions) and tails~/.claude/projects/<cwd-slug>/<cliSessionId>.jsonl. - Entrypoint-tagged transcript (fallback). If the index is not where
hhexpects it, a new transcript for the current directory is accepted only if its records sayentrypoint: "claude-desktop". A terminalclaudesession in the same directory (entrypoint: "cli") is rejected with a reason pointing athh run -- claude.
| OS | Session index | Transcript | Status |
|---|---|---|---|
| Linux | $XDG_CONFIG_HOME/Claude/claude-code-sessions/ (default ~/.config/Claude/…) |
~/.claude/projects/<cwd-slug>/<id>.jsonl |
Index discovery tested against a captured fixture |
| macOS | ~/Library/Application Support/Claude/claude-code-sessions/ |
~/.claude/projects/<cwd-slug>/<id>.jsonl |
Unverified — expected by analogy; please report |
| Windows | %APPDATA%\Claude\claude-code-sessions\ |
%USERPROFILE%\.claude\projects\<cwd-slug>\<id>.jsonl |
Unverified — the slug rule for drive letters has not been checked |
On macOS and Windows the paths are the ones Electron's userData convention
predicts, but no fixture has been captured there yet. If discovery fails the
session is recorded with adapter_status = degraded and a reason that names
the directories that were searched — it never reports active with zero
steps. Run HH_DEBUG=1 hh run --adapter claude-desktop -- … for the full
discovery trace and attach it to an issue.
When the recording ends, the adapter reads the transcript to its end before finalizing, so turns written right up to the moment you exited the shell are kept. Turns Desktop writes after that are not — start a new recording.
Adding a new adapter
Adapters consume untrusted JSONL, so per the 1.0 stability addendum every adapter parser must:
- Never panic on malformed input — errors only.
- Have a fuzz target under
fuzz/(e.g.fuzz/fuzz_targets/<name>.rs). - Ship with a fixture corpus under
tests/fixtures/<adapter>/for integration tests — a sanitized real capture with aNOTES.mdon its provenance and where the agent writes session data per OS (seehh-core/tests/fixtures/claude-desktop/for the model), never a hand-written approximation.
See CONTRIBUTING.md ("Adding an adapter") for the fixture-capture guide and
the exact files to touch (hh-core's adapter module, the detection rules, the
fuzz target, and the fixture corpus).