# Harness Trace Capture Notes

Last checked on Anvil: 2026-04-29.

## Installed CLI Versions

- Claude Code: `2.1.123`
- Codex CLI: `codex-cli 0.125.0`
- OpenCode: `1.14.26`
- Kimi CLI: `1.37.0`

## Claude Code

Use non-interactive stream JSON and enable partial/hook/debug emission:

```sh
claude \
  --dangerously-skip-permissions \
  --print --verbose \
  --output-format stream-json \
  --include-partial-messages \
  --include-hook-events \
  --debug-file "$RUN_DIR/claude_debug.log" \
  --model "$MODEL" \
  --effort max \
  --add-dir "$AGENT_WORK" \
  -p "$PROMPT" \
  > "$RUN_DIR/transcript.jsonl" \
  2> "$RUN_DIR/stderr.log"
```

Notes:

- `--effort` accepts `low`, `medium`, `high`, `xhigh`, and `max`.
- `--include-partial-messages` is the closest stream-level output for latency/tokens.
- `--include-hook-events` helps reconstruct tool lifecycle overhead.
- `--debug-file` captures lower-level CLI diagnostics outside stdout JSON.

## Codex CLI

Use JSONL event output and override config values on every run:

```sh
codex exec \
  --json \
  -m "$MODEL" \
  -c 'model_reasoning_effort="xhigh"' \
  -c 'model_verbosity="high"' \
  -c 'model_reasoning_summary="detailed"' \
  -c 'hide_agent_reasoning=false' \
  -c 'show_raw_agent_reasoning=true' \
  --dangerously-bypass-approvals-and-sandbox \
  --skip-git-repo-check \
  "$PROMPT" \
  > "$RUN_DIR/transcript.jsonl" \
  2> "$RUN_DIR/stderr.log"
```

Notes:

- `--json` emits JSONL events on stdout.
- Token usage is available on `turn.completed` events and in persisted session JSONL under `~/.codex/sessions`.
- Raw reasoning may still be unavailable or encrypted depending on model/account policy, but these config flags prevent the CLI from hiding anything it is allowed to show.
- `tools/codex_json_metrics.py` summarizes Codex JSONL into `codex_metrics.json`.

## OpenCode

Use raw JSON events, model variant, thinking blocks, and post-run export:

```sh
opencode run \
  --pure \
  --format json \
  --thinking \
  --variant "$REASONING_EFFORT" \
  --dangerously-skip-permissions \
  -m "$MODEL" \
  "$PROMPT" \
  > "$RUN_DIR/transcript.jsonl" \
  2> "$RUN_DIR/stderr.log"

opencode export "$SESSION_ID" > "$RUN_DIR/opencode_export.json"
```

Notes:

- `--format json` emits raw JSON events.
- `--thinking` asks OpenCode to include thinking blocks when the provider exposes them.
- `--variant` is provider-specific and maps to reasoning effort for supported models.
- `opencode export` gives a full session JSON artifact when a session ID is visible in the JSONL.

## Visualizer Contract

The run viewer treats these as primary trace artifacts:

- `transcript.jsonl`
- `stderr.log`
- `codex_metrics.json`
- `codex_session.jsonl`
- `opencode_export.json`
- `claude_debug.log`

The viewer summarizes known token fields and exposes a raw Harness JSON tab for the full event stream preview. Provider-specific schema changes should be handled by adding parser branches to `summarize_transcript` and `summarize_harness_events` in `tools/render_run_viewer.py`.