Claude Code persistent sessions, what works out of the box and what you have to wrap

What “persistent” actually means in the CLI today

When the CLI runs a turn, it appends to a JSONL file under your home directory. The path is deterministic from the working directory: take the absolute path, replace every non-alphanumeric character with a hyphen, that is the folder name. Each session inside that folder is one file, named after its session ID. The transcript contains the user prompt, every tool call the agent issued, every tool result, and every assistant response, in order. The file is written incrementally so a crash mid-turn does not lose the prior turns. Nothing about this stops when you quit the CLI or reboot your Mac.

That is the persistent-sessions story you read about in the Anthropic docs. It is accurate and it is enough for a lot of people. The interesting question is what happens when you want the next layer up.

Three things the JSONL layer does not give you

These are the three gaps that turn “Claude Code already persists sessions” into “Claude Code sessions keep disappearing on me.” All three are real, all three are well-defined, and all three live above the transcript layer.

1. There is no auto-restore on launch

The CLI is, by design, stateless across invocations. You open a terminal, you typeclaude, you get a fresh session unless you remember to pass a flag. If you had four sessions open across four projects, that is four terminals, four cd commands, and four --continue flags. The transcripts are still on disk, but the workspace is not restored, the per-window model selection is not restored, and you are the one rebuilding the map every morning.

2. Auto-compact silently trims older context

When a session approaches the model’s context window, the SDK fires a compact_boundary event with a trigger of auto or manual and a preTokens count, then emits a compaction_start status change and a stream of compaction_delta chunks while it rewrites the older half of the conversation into a shorter summary. The summary replaces the originals in the live model window. The JSONL still has the full text. The model does not. In a long session this is where the agent “forgets” the path you established ninety turns ago: not because the file lost it, but because the live window did.

3. Forking is a manual session-id dance

If you want to try two different directions from the same point in a conversation, the best the CLI gives you is two terminals running --resume on the same ID. From that point they diverge with no parent-child link in the transcript file, no way to compare what each branch produced, and no UI affordance. The ACP layer (the protocol Claude Code speaks to its host) has an unstable session/fork RPC that creates a real branched session at a specific message. The CLI does not surface it. A host can.

What it looks like when a host owns the experience

The patch for all three gaps is structural, not heroic. A host that sits above ACP keeps its own registry of open windows (so it can recreate them on launch), keeps an append-only chain of every upstream session ID a conversation has owned (so rate limits do not strand history), and exposes the unstable fork RPC as a button. The same loop, with a different envelope around it.

The actual code, in one shipping wrapper

Fazm is one of the hosts I work on. It is a native macOS app that runs the real Claude Code agent loop through ACP. The MIT-licensed source is at github.com/m13v/fazm. The three places that handle the three gaps:

Window auto-restore lives in Desktop/Sources/FloatingControlBar/DetachedChatWindow.swift. Function restoreWindows at line 644 reads a registry of every detached window from UserDefaults, loads the chat history for each (retrying up to 10 times with a 0.5 second sleep before deferring to the next launch), rebuilds each window at its saved frame, workspace directory, and selected model, and wires up the same callbacks the original window had.

// Desktop/Sources/FloatingControlBar/DetachedChatWindow.swift, line 644
func restoreWindows(chatProvider: ChatProvider) {
    guard let data = UserDefaults.standard.data(forKey: Self.registryKey),
          let snapshots = try? JSONDecoder().decode([WindowSnapshot].self, from: data),
          !snapshots.isEmpty else { return }
    for snapshot in snapshots {
        Task { @MainActor in
            var savedMessages: [ChatMessage] = []
            for attempt in 0..<10 {
                savedMessages = await ChatMessageStore.loadMessages(
                    context: "__\(snapshot.sessionKey)__",
                    limit: 100
                )
                if !savedMessages.isEmpty { break }
                try? await Task.sleep(nanoseconds: 500_000_000)
            }
            // ...rebuild window at savedFrame, workspace, model
        }
    }
}

The session-ID chain that outlives upstream rollovers lives in Desktop/Sources/Providers/ChatProvider.swift. Constant sessionChainMaxSize = 16 at line 614, helper appendToSessionChain at line 626. Every time the bridge hands back a new upstream session ID (because the old one was rate-limited or expired), the chain appends. On every send, the host loads recent messages across the full chain and forwards them as the preamble. The model sees one continuous conversation, the bridge sees whatever fresh session ID is current.

One-click fork lives in acp-bridge/src/index.ts, function handleForkSession at line 3824. It dispatches the upstream session/fork RPC (the unstable method exposed by @agentclientprotocol/claude-agent-acp via unstable_forkSession), registers the new session under the requested key, and sends back a session_forked event the UI uses to open the new window. The source session stays alive on disk.

// acp-bridge/src/index.ts, line 3824
async function handleForkSession(msg: ForkSessionMessage): Promise<void> {
  const sourceEntry = sessions.get(msg.fromSessionKey);
  if (!sourceEntry) {
    logErr(`forkSession: source session not active; cannot fork`);
    send({ type: "error", message: `Cannot fork: no active session` });
    return;
  }
  const result = await acpRequest("session/fork", {
    sessionId: sourceEntry.sessionId,
    cwd: msg.cwd ?? sourceEntry.cwd,
    mcpServers: buildMcpServers(mode, cwd, msg.toSessionKey),
  }) as { sessionId: string };
  registerSession(msg.toSessionKey, { sessionId: result.sessionId, cwd, model });
  send({
    type: "session_forked",
    fromSessionId: sourceEntry.sessionId,
    toSessionId: result.sessionId,
    fromSessionKey: msg.fromSessionKey,
    toSessionKey: msg.toSessionKey,
  });
}

None of this is heroic. The window registry is a JSON blob in UserDefaults. The chain is a deduped string list capped at sixteen entries. The fork is one RPC call. The payoff is that the experience of opening the app feels like opening a workspace instead of opening a terminal.

Picking the right rung

If you are a CLI-first user and you already script around --continue, the bare flag is fine. You can keep a tmux session alive across reboots, your terminal multiplexer holds your cwd, and the JSONL is doing the right thing under you. Most of the time it works. The places where it breaks (long runs, rate limits, branches) are real but rare for any given user.

If you find yourself losing context once a week and you can tell me which file path the agent forgot, you are hitting auto-compact, and the answer is either to keep sessions shorter or to move to a host that keeps the full history live. If your conversations die during the rate-limited part of the afternoon, you are hitting an upstream session roll, and the answer is a chain (build your own or use a wrapper that has one). If you want to try two directions on the same problem, you want a fork button.

Pick the lightest layer that fixes the specific gap you have. You do not need a desktop wrapper to use Claude Code well. You do need one if you want the persistent-sessions experience without the per-restart ritual.