Claude Code persistent sessions and forking, explained

The three layers of persistence

Forking only makes sense once you see how a Claude Code session persists in the first place. There are three layers, each with its own lifetime, its own fork story, and its own way of getting out of sync with the other two.

Layer 1 is the only one Claude Code itself manages, and the only one a fork operates on directly. Layer 2 and Layer 3 are the host's problem. On a hosted product like ours, that means the E2B sandbox lifecycle and a per-session git index in /app. On a single laptop running the CLI, it is just your normal working directory. Either way, the fork only copies the transcript.

Where the JSONL actually lives

Claude Code stores every session as one JSONL file under ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl. The <encoded-cwd> is the absolute working directory with every non-alphanumeric character replaced by a dash. A session started in /Users/me/myproj lands under ~/.claude/projects/-Users-me-myproj/. Each event is one line of JSON.

The practical upshot of one-file-per-session: a fork is literally file copy plus new id. A session move between machines is scp. A long-term archive is git add. You can list everything Claude Code knows about for the current project with one line of shell, no API call:

ls ~/.claude/projects/$(pwd | sed 's:[^a-zA-Z0-9]:-:g')/

That is also why --fork-session feels so cheap. The whole operation is reading one JSONL file, assigning a new session id, and writing a copy alongside it. No network call, no service to coordinate, no migration. Every subsequent prompt on the new id appends to its own file; the original keeps appending to its own. They diverge from byte 0 of the next event.

What fork copies, and what it leaves shared

This is the part most guides skip and the part that bites in production. The fork is a conversational fork. It does not clone your filesystem.

If you fork mid-edit and the agent on the new branch starts writing files, the agent on the original branch sees those files the next time it lists the directory. Two forks pointing at one workspace is one workspace, period. The remedies are either serialise (one active fork at a time per workspace), clone (each fork gets its own checkout), or virtualise (each fork gets its own sandbox). On mk0r we mostly serialise per session, and for the rare parallel case we clone into a fresh checkout from the SHA the fork was anchored to.

How the fork call flows through the Agent Client Protocol

When Claude Code runs as an embedded agent, every session lifecycle operation is a JSON-RPC method on the Agent Client Protocol. The fork is one of them. Below is the round trip when a host (say, a web app) asks the agent to fork an existing session.

The interesting line is the second one. The ACP entry point calls a single method, createSession, and that one method handles all four lifecycle paths: newSession, resumeSession, loadSession, and forkSession. The agent disambiguates them with creationOpts.forkSession and creationOpts.resume. In our codebase, that disambiguation lives at docker/e2b/files/opt/patched-acp-entry.mjs, where we wrap ClaudeAcpAgent.prototype.createSession once and get hooks on all four lifecycle paths for free. That one-chokepoint design is why a forked session in our environment still streams compaction events, retry events, and cost metadata the same way a fresh one does.

The workspace side of the fork

When the transcript forks but the workspace does not, you get drift. A practical example, drawn from how our sandbox handles undo and redo: every assistant turn that mutates /app is committed to a local git repo with a generated message, and the resulting SHA is appended to a per-session historyStack with an activeIndex pointer. Undo walks the pointer back one SHA and reverts the tree; redo walks it forward.

Here is the part that mirrors the transcript fork story almost exactly:

// src/core/e2b.ts (around line 1930)
session.historyStack = session.historyStack ?? [];
if (
  typeof session.activeIndex === "number" &&
  session.activeIndex >= 0 &&
  session.activeIndex < session.historyStack.length - 1
) {
  // New commit arrived while we were "in the past"
  // Drop everything past the active index.
  session.historyStack = session.historyStack.slice(
    0,
    session.activeIndex + 1
  );
}
session.historyStack.push(sha);
session.activeIndex = session.historyStack.length - 1;

This is the destructive case. The user has undone three turns, then asks the agent to do something new. The new commit appends at the active index; everything past it is thrown away. The workspace has chosen one timeline and forgotten the other. That is exactly the situation --fork-session is designed to prevent on the transcript side. The way out is the same on both sides: before the destructive move, fork. On the transcript, call /branch. On the workspace, snapshot the SHA into a side reference before the truncate would happen. We pair those two operations behind a single user-visible action so they cannot drift.

What survives a paused sandbox

Persistent sessions sit between two extremes. On one end, a laptop running Claude Code locally is persistent in the boring sense: the disk does not go away unless you delete files. On the other end, a serverless agent that boots fresh on every request has no persistence at all. The interesting middle is a sandbox that pauses when idle and resumes on demand, which is what we run.

The rules are simple, but they bite if you skip them. The persistent disk ( /app, /root) survives pause and resume. /run is tmpfs and gets wiped, so any credentials or sockets you wrote there are gone. The Claude credentials at ~/.claude/.credentials.json survive, but their refresh tokens rotate, so blindly pushing a host-cached copy of the file on resume will force re-auth (the fix is to merge, not overwrite). The transcript JSONL at ~/.claude/projects/.../<id>.jsonl survives. Forking on the resume side of a pause works exactly the same as forking before it, because the file the fork operates on never went anywhere.

A short mental model

Treat the JSONL as the source of truth for the conversation, the working directory as the source of truth for the artefact, and the agent process as a stateless interpreter that loads one from the other at the start of each session. Forking is then a one-line operation on the conversation: copy the JSONL, hand the new id to a fresh interpreter. Anything you want to fork about the artefact is your problem, and the cheapest answer in practice is a git SHA you can checkout into a sibling directory.

Once the model clicks, the slash command and the CLI flag stop being two features and start being two ergonomics for the same file copy. Pick whichever one matches the moment.