claude-code - 💡(How to fix) Fix Persist parent-session lineage (`forked_from_id`) in transcript JSONL for `/branch` and `/clear`

Summary

Claude Code transcripts (~/.claude/projects/<project>/<session-id>.jsonl) carry no on-disk pointer linking a session back to the session it originated from. When a conversation forks (/branch) or starts fresh (/clear, alias /new), the new session is written to a new JSONL with a new session UUID, but nothing in the file records its parent. This makes session lineage impossible to reconstruct from disk — which local/offline tooling depends on.

Problem / motivation

I build a local, offline session-analytics tool that reads the transcript JSONL files directly. Two common operations break lineage:

• /clear starts a new conversation (per the docs, "Start a new conversation with empty context… The previous conversation stays available in /resume"), which produces a new session UUID and a new transcript file. The /clear command is recorded as the first event of the new file, but with no reference to the prior session.
• /branch surfaces both the original and new session IDs in the CLI, but (as far as I can tell from inspecting transcript files) does not appear to persist the parent ID into the new session's JSONL.

Without a persisted parent pointer, tools cannot:

• Reconstruct a "work thread" that a user fragmented across several /clears.
• Attribute cost/tokens correctly across a fork tree (a fork that carries forward prior history will otherwise double-count that history's spend).
• Offer "jump to the session this was forked from" navigation.

Proposed solution

Persist the originating session ID in the new session's transcript — e.g., a top-level/meta field such as parentSessionId (or forkedFromSessionId) written into the first record of a /branch- or /clear-created session. Omitting the field for ordinary (non-derived) sessions is fine.

Prior art

OpenAI's Codex CLI already does exactly this: forked sessions write session_meta.forked_from_id (the parent thread ID) into the rollout JSONL, and omit the field entirely for non-forked sessions. This is enough for downstream tools to rebuild the fork tree with certainty.

Use cases

• Local analytics: correct cost attribution across forks; dedup of copied history.
• Session navigation: "forked from →" links between related sessions.
• Resilience: a durable lineage record that survives independent of the CLI's in-memory /resume picker.

Additional notes

Verified against Claude Code v2.1.x transcripts and the public docs (sessions.md, commands.md). Happy to share anonymized JSONL examples showing the missing linkage if useful.