build-transcript

build-transcript

buildreadhands-off

Use this when: you want this session exported for analysis or learning

Build transcript

A conversation is the richest training signal the harness produces — but only if it's captured faithfully. The trap is reconstructing it from memory, which quietly paraphrases and drops turns; the fix is to read the actual record.

Contract — task class: build- (creates an artifact) · tools: Agent (dispatch one fork), Bash (locate the JSONL), SendUserFile (deliver) · the fork does the heavy read+distil in its own window so the raw log never bloats this thread · verifiable artifact: a markdown transcript at /tmp/…, delivered to the maintainer as a download, not written into the repo.

1 · Locate the session record

The current session's transcript is a JSONL on disk: ~/.claude/projects/<cwd-slug>/<session-id>.jsonl (cwd-slug = the absolute cwd with every non-alphanumeric char replaced by -; session id is $CLAUDE_CODE_SESSION_ID). Sidechain (sub-agent) transcripts sit in a subagents/ sub-dir beside it. Resolve the path with find ~/.claude/projects -name "$CLAUDE_CODE_SESSION_ID.jsonl".

2 · Dispatch a fork to distil it

This is the skill. Dispatch one fork subagent (subagent_type: "fork") — a fork inherits this entire conversation, so it already understands the arc; pair that with the JSONL for exactness. A plain subagent would start blank and only get its prompt — the fork is what lets the helper see the chat without re-passing it (and it works in its own window, so this thread stays clean). See docs/learnings/2026-06-14-fork-subagent-inherits-parent-context.md.

Brief the fork to:

• Read the session JSONL (path from step 1) — and the subagents/*.jsonl sidechains — as the ground-truth source for verbatim wording, using its inherited understanding of the conversation only to judge what matters.
• Produce the markdown in the format below.
• Write it to /tmp/transcript-<date>-<slug>.md (slug from the session topic).
• Return only the file path + a one-line summary — never the transcript body (that would refill this thread, defeating the point).

3 · Deliver — never commit

SendUserFile the /tmp path to the maintainer as a download (status: normal). Do not write it under the repo or git add it — it is a throwaway hand-off artifact, not project history.

Format (what the fork builds)

Optimised for an agent to digest and learn from:

• Metadata header — topic · which skill(s) were exercised · turn count · outcome. Orients the reader before the detail.
• Course-correction index — up front, list the moments the maintainer steered or corrected the agent (with anchors). These are the highest-value learning points; surface them rather than burying them mid-scroll.
• Verbatim where it's load-bearing. User turns always verbatim (their wording is the signal). Assistant turns distilled, but kept verbatim at the moment a decision / claim / recommendation is made. Tool results → only the decision-relevant facts, not raw dumps. Show tool calls (commands, agent dispatches) where they drove a decision.
• Sidechains folded in, clearly marked — the sub-agent work and failures are often where the real lessons live.
• Redaction pass — scrub tokens, secrets, PII (these transcripts get shared).
• Markdown only — it's the most natural format for an agent to parse prose from; no timestamps unless asked.