Add Push Compact Transcripts Option

Claude Code·Opus 4.8·computermode·3mo ago·26hr 38min·1 Checkpoint·6 file changes·+396/-29·72K tokens

similar to strategy_options.push_sessions, we want strategy_options.push_compact_transcripts that can be true or false. when it's true, transcript.jsonl is pushed (the code for generating transcript.jsonl lives in compact/*)

3mo ago·20h

Done. All 6226 unit tests pass, lint is clean. Here's what I built:

How it works

Since push_sessions gates pushing the entire/checkpoints/v1 branch as a whole, the way to get transcript.jsonl pushed is to include it in the checkpoint tree: when strategy_options.push_compact_transcripts is true, every checkpoint write stores a condensed transcript.jsonl (generated by transcript/compact from the already-redacted full.jsonl content) next to full.jsonl in the session subdirectory. It then rides along on every push of the checkpoints branch. Default is false — nothing changes unless the option is explicitly set to true.

Changes

  • settings/settings.go — IsPushCompactTranscriptsEnabled() method plus a context-loading package-level variant, following the existing IsFilteredFetchesEnabled/IsSignCheckpointCommitsEnabled patterns. Only an explicit boolean true enables it.
  • checkpoint/committed.go — writeTranscript now calls writeCompactTranscript when the setting is on. It runs after the Codex sanitization step so the compact converter sees the same bytes as full.jsonl. Generation is best-effort: a conversion or blob failure logs a warning and never blocks the checkpoint write, since hooks have no retry path.
  • paths/paths.go — new CompactTranscriptFileName = "transcript.jsonl" constant.
  • agent/registry.go — new NameForAgentType() helper with a static display-type → registry-slug map (e.g. "Claude Code" → "claude-code"), falling back to the live registry for external agents. The compact format's agent field wants the slug, and a static map keeps it deterministic regardless of which agent packages are linked in.
  • Docs — updated the checkpoint layout diagrams in committed.go, checkpoint.go, and docs/architecture/sessions-and-checkpoints.md with the new optional file and a paragraph explaining the option.

Tests

  • TestIsPushCompactTranscriptsEnabled (settings): missing / true / false / wrong-type cases.
  • TestWriteCommitted_CompactTranscript (checkpoint): with the option enabled, transcript.jsonl lands in the session tree with the compact format ("agent":"claude-code"); disabled by default, only full.jsonl is written.

Two design notes worth knowing: the compact transcript covers the full session (same scope as full.jsonl, no StartLine truncation), and it's written as a single blob — no chunking, since compact output is much smaller than the full transcript. Also, because each session write clears its subdirectory first, turning the option off stops including the file on the next checkpoint write.

3mo ago·25.5s

Now launching the 4 review agents in parallel:

3mo ago·20m

Review complete — fmt, lint, and tests all pass. Summary:

Fixed

  1. Duplicate warn-log blocks in writeCompactTranscript (committed.go) — collapsed the two near-identical warning blocks (Compact failure, blob failure) into a single error-chained path with one log statement.
  2. Hidden-artifact covenant undocumented (altitude) — the doc comment now states explicitly that transcript.jsonl is deliberately not recorded in SessionFilePaths/CheckpointSummary, so future readers know the asymmetry is intentional rather than an oversight.

Skipped, with reasons

  • Thread settings through WriteCommittedOptions instead of loading in the store (efficiency + altitude, same mechanism): the store already reads settings this way (IsSignCheckpointCommitsEnabled in the same file), the cost is one small JSON parse per checkpoint write — negligible next to the git tree operations around it — and changing WriteCommittedOptions would ripple through the strategy layer and its tests. Consistency with the existing pattern wins here.
  • Remove NameForAgentType / the static map (simplification and altitude pulled in opposite directions — one wanted map-only inlined, the other registry-only): the two-tier design is the deliberate middle ground. The registry fallback already covers the drift concern (a new agent registered via init() resolves correctly in the real binary even if the map isn't updated), and the static map gives deterministic results regardless of which packages are linked in. The mapping also belongs in the agent package next to the constants, not inlined in checkpoint.
  • addBlobEntry helper for the TreeEntry literal pattern (reuse): the pattern repeats 10+ times in pre-existing code; adding a helper used once by new code wouldn't reduce duplication, and refactoring all the existing sites is well outside this diff.
  • Docstring wording on the method/function pair in settings.go: it mirrors the existing IsSignCheckpointCommitsEnabled pair exactly; deviating would be less consistent, not more.