Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] Forked session storage docs still describe each transcript as a full copy [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#52205•Fetched 2026-04-23 07:33:47
View on GitHub
Comments
0
Participants
1
Timeline
3
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×3
RAW_BUFFERClick to expand / collapse

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/claude-directory

Section/Topic

Application data (projects/<project>/<session>.jsonl) and forked-session transcript storage semantics

Current Documentation

The docs currently say:

| projects/<project>/<session>.jsonl | Full conversation transcript: every message, tool call, and tool result |

The Agent SDK session docs also say:

  • Move the session file. Persist ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl from the first run and restore it to the same path on the new host before calling resume. The cwd must match.

What's Wrong or Missing?

Changelog v2.1.118 says: Fixed /fork writing the full parent conversation to disk per fork — now writes a pointer and hydrates on read.

That means forked sessions are no longer stored as a full standalone copy of the parent conversation on disk. The current docs still describe each session JSONL as a full transcript, and the cross-host resume guidance implies that copying a single session file is sufficient.

For forked sessions, that storage description is now outdated. Users who inspect transcript files for privacy/storage reasons, or who move session files between hosts, need the docs to explain that a fork can depend on parent-history data instead of duplicating the entire conversation into the fork's own file.

Suggested Improvement

Update the storage docs to distinguish logical session history from on-disk fork storage.

Suggested changes:

  1. In claude-directory, revise the projects/<project>/<session>.jsonl row to clarify that forked sessions may store parent-history references rather than a full duplicated transcript.
  2. In agent-sdk/sessions, add a note in Resume across hosts explaining the fork-parent dependency when copying/restoring forked sessions.
  3. If hydration requires the parent chain to be present, state that explicitly and give the minimum safe migration rule for forked sessions.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

PageContext
https://code.claude.com/docs/en/claude-directoryApplication data table currently says each session JSONL is a full transcript
https://code.claude.com/docs/en/agent-sdk/sessionsResume-across-hosts guidance currently tells users to move a single session file

Total scope: 2 pages affected

Source: Changelog v2.1.118

Exact changelog entry: Fixed /fork writing the full parent conversation to disk per fork — now writes a pointer and hydrates on read

extent analysis

TL;DR

Update the documentation to reflect that forked sessions store parent-history references instead of full duplicated transcripts.

Guidance

  • Review the claude-directory and agent-sdk/sessions documentation to ensure accuracy regarding forked session storage.
  • Update the projects/<project>/<session>.jsonl row in claude-directory to clarify that forked sessions may store parent-history references.
  • Add a note in Resume across hosts in agent-sdk/sessions to explain the fork-parent dependency when copying/restoring forked sessions.
  • Consider adding information on the minimum safe migration rule for forked sessions, if hydration requires the parent chain to be present.

Example

No code snippet is necessary for this issue, as it is related to documentation updates.

Notes

The suggested improvements should be reviewed and tested to ensure accuracy and clarity. The changes should be made to the affected pages, which are https://code.claude.com/docs/en/claude-directory and https://code.claude.com/docs/en/agent-sdk/sessions.

Recommendation

Apply the suggested documentation updates to reflect the correct behavior of forked sessions, as the current documentation is outdated and may cause confusion for users.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#orchestration issue#cache issue#memory leak#API versioning#request timeout

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [DOCS] Forked session storage docs still describe each transcript as a full copy [1 participants]