Sessions, persistence, and remote

This chapter treats sessions as the durable spine of Claude Code. A session is not only a chat transcript: it is a local JSONL event stream, a resume/continue target, a fork/rewind boundary, a possible remote-control handoff point, and—when attached by its host—a view into durable claude.ai Project knowledge.

Read this chapter when the question is: where did the agent’s state come from, where was it saved, and how can it be resumed, forked, rewound, or controlled remotely?

Source-anchor policy

This page is a chapter guide. Linked implementation pages carry concrete cli.renamed.js anchors.

Semantic alias	Minified anchor	Scope
Sessions/persistence/remote chapter	N/A — navigation page	Groups local JSONL transcripts, resume/continue/fork/rewind, hosted sessions, teleport, Remote Control, and remote-runner egress/file staging.
Session implementation pages	See linked source-anchor tables	Concrete bundle anchors live in destination pages.

Session spine

flowchart TD
    Startup[CLI mode selection] --> NewOrResume{new / continue / resume?}
    NewOrResume --> New[Fresh session]
    NewOrResume --> Continue[Continue latest]
    NewOrResume --> Resume[Resume by id/search]
    Continue --> Restore[Restore transcript]
    Resume --> Restore
    Restore --> Loop[Interactive or headless loop]
    New --> Loop
    Loop --> Jsonl[local-jsonl transcript]
    Loop --> Remote[cloud / teleport / Remote Control]
    Remote --> DataPlane[agent proxy / working sync / file staging]

Primary reading order

This chapter uses four documentation layers so one session fact does not acquire several competing owners:

Layer	Canonical pages	Reader contract
Architecture	Session and remote-control architecture	Defines identities, layers, collaborators, and invariants; it does not repeat queue/hydration algorithms.
Lifecycle	Session resume and transcripts, Remote control and teleport, Remote-environment egress and file staging	Owns setup, state transitions, retries, persistence ordering, remote-runner data planes, cleanup, and failures.
Inventory/reference	Session API, events, and storage	Lists endpoint, event, frame-family, and storage surfaces without becoming their implementation tutorial.
Shape/reference	Data models and frame schemas	Defines observable record/frame fields and ordering constraints without duplicating lifecycle algorithms.

Order	Page	Session question answered
1	Session resume and transcripts	How do JSONL roots, --continue/--resume/fork/no-persistence/rewind and /clear//branch//rename//recap connect, and how do discovery/restore rehydrate live state?
2	Hosted Projects and knowledge	How does CLAUDE_PROJECT_UUID bind one session to one shared knowledge container, and how do project context, read/search/write/delete, OAuth scopes, and upload guards work?
3	Team onboarding and share flows	How does /team-onboarding scan local session usage, draft ONBOARDING.md, and optionally create/update an organization share link?
4	Remote control and teleport	How do --cloud/deprecated --remote, --teleport, Remote Control, bridge tokens, /remote-env, /web-setup, and /session connect to sessions?
5	Remote-environment egress and file staging	How do hosted runners provide policy-enforced HTTPS egress, working-file synchronization, /uploads, and staged MCP file lanes?
6	Session API, events, and storage	Which API endpoints, event families, bridge frames, and internal storage areas are visible around sessions and remote control?
7	SDK query, session API, and subagent surface	What programmatic SDK surface does Claude Code expose for query, session management, subagent inspection, in-process MCP, and direct-connect transport?
8	Session recording (asciicast)	How are session recordings represented, retained, and bounded when the source-visible asciicast path is active?
9	Data models and frame schemas	Which observable transcript records, session layers, stream/control frames, and storage record families shape sessions?
10	Session and remote-control architecture	How is a session decomposed into a durable JSONL layer + live envelope, and how do resume/fork/rewind/remote reuse the same address?

Handoffs

• Startup mode selection is documented in Runtime lifecycle.
• Stream-JSON headless frames are documented in Context and model loop.
• File checkpoints, context-collapse metadata, and rewind mechanics are detailed in Context, memory, compaction, checkpoints, and rewind.
• Permission forwarding and tool execution are documented in Tools, integrations, and security.
• Other hosted creation surfaces are documented in Artifact publishing and live pages and Claude Design and design-system sync.
• Protocol families across remote, bridge, MCP, agents, and provider streaming are documented in Runtime communication protocols.

Navigation

• Start here
• Full table of contents