Claude Code stores every session as a JSONL file on the machine where it ran. There is no built-in cross-machine sync as of early 2026 — sessions are local-by-design. This article describes where the files actually live, what's in them, what's portable, and the practical patterns people use to maintain continuity across machines anyway.
Where conversations live
Every Claude Code session writes a JSONL file under:
~/.claude/projects/[encoded-workspace-path]/[session-id].jsonlThe encoded workspace path is your workspace's absolute filesystem path with forward slashes and spaces replaced by hyphens. /Users/larry/My Project becomes -Users-larry-My-Project. The session ID is a UUID generated when the session starts.
Each line of the JSONL is a single message — user input, assistant response, or tool call/result — in the order they happened. The format is structured but not strictly documented as a public API; assume it can change between Claude Code versions.
What's in the file
A session JSONL contains the full conversation: user prompts, assistant responses, every tool call, every tool result, and metadata like timestamps and tool execution status. It does not contain:
- The contents of files Claude read (only the file paths and Claude's interpretation of them)
- The state of your workspace at any given moment (only the changes Claude made, embedded as tool calls)
- Auth tokens, API keys, or other secrets (those live in
~/.claude.json, not in session files)
This matters because moving a JSONL to another machine doesn't move your workspace. The session references file paths, and on the new machine those paths only resolve correctly if the workspace is at the same absolute path with the same content.
What's portable, what isn't
Portable. The conversation transcript is portable — you can read a JSONL file on any machine to see what happened. PRIMA Memory and similar session-history MCP servers index these files and expose them as searchable history.
Not portable. The --resume command on Machine B will not find sessions that ran on Machine A. --resume reads from the local ~/.claude/projects/[workspace]/ directory; if the file isn't there, the session doesn't exist for resume purposes. Even if you copy the JSONL to Machine B's projects directory, the session ID alone may not be enough — Claude Code's session resumption assumes workspace state matches the session's reference points.
In practice, copied JSONL files are useful as read-only history — you can see what happened, search them, summarise them — but treating them as resumable sessions on a different machine is unreliable.
Three practical patterns
Pattern 1: Treat conversations as ephemeral
The simplest approach. Conversations are means-to-an-end; the durable record is the workspace itself — committed code, updated CLAUDE.md, written notes, completed tasks. Each machine has its own conversation history; you don't try to sync them.
This works well when:
- You commit changes frequently, so the work is captured in git
- You write session summaries into tracked files (project notes, session logs, CLAUDE.md updates)
- You don't often need to reconstruct what was discussed mid-session — the outcome is what matters
For most users, this is the right default. The desire for full conversation sync is usually a desire to recover from poor session-end discipline. Solve the discipline problem instead.
Pattern 2: Workspace-level checkpoint files
End each session by writing a checkpoint to a tracked file in the workspace. The checkpoint covers: what was done, what's pending, where to pick up next time. Commit it. The next session — on this machine or another — reads the checkpoint and resumes from the explicit handoff, not from the raw conversation.
This is what tools like the /save and /resume patterns in PRIMA workspaces do. It's also what a manually-maintained SESSION-LOG.md in the workspace can do without any tooling — just a discipline of writing what you did before closing the session.
Why this works better than syncing JSONLs: the checkpoint is the curated, intentional summary. The JSONL is raw transcript including dead-ends, false starts, and tool noise. The checkpoint is what the next session actually needs.
Pattern 3: Session-history MCP servers
An MCP server that indexes session JSONL files and exposes them via tools Claude can call from any future session. PRIMA Memory is one example; there are others.
This solves "I want to search my past Claude sessions" — Claude can call a tool like search_history("authentication refactor") and find relevant past discussions. It does not by itself solve cross-machine sync — each machine still indexes its own JSONL files. To share the history, you sync the underlying database file (typically SQLite) between machines, the same way you'd sync any other data file.
If you want this pattern:
- Install the MCP server on each machine
- Decide where the database lives — local-only per machine (no sync), or in a synced location (Dropbox, iCloud Drive, a shared workspace folder, a git-tracked file with care)
- If syncing, accept that two machines writing to the same database simultaneously can corrupt it — coordinate, or use a server that handles concurrent writes
The convenience is real; the operational complexity is not zero. For most people, Pattern 2 (checkpoint files) gives 80% of the benefit at 20% of the cost.
What about claude.ai conversations?
Conversations from claude.ai (the web interface) and Claude Desktop are stored separately from Claude Code and aren't migrated to or from Claude Code's session files. Claude Code can in some cases resume conversations that began in the web app via integration features, but that's a one-direction handoff, not bidirectional sync. Don't expect a session you started in the browser to show up in ~/.claude/projects/.
Anthropic's official position
As of early 2026, Anthropic does not publish a documented cross-machine session sync feature for Claude Code, and has not announced one as planned. The implicit position is that workspaces are the source of truth and conversations are tooling — durable artefacts go in git, conversations are how you produce them.
This is a defensible position. Trying to sync conversation history at file level would create real problems: workspace path mismatches, secret leakage in synced JSONLs, conflict resolution between concurrent sessions, version skew between Claude Code releases. The friction of building good session-end discipline is much lower than the friction of solving full sync correctly.
Practical recommendation
Pick one of three:
- Default: ephemeral conversations, durable workspace. Commit often, update CLAUDE.md, write session summaries into tracked files. Most users don't need more than this
- If you bounce between machines daily: add explicit checkpoint files. End each session writing what was done and what's next, into a tracked file. Read it on the other machine to pick up
- If you genuinely need to search past sessions across machines: install a session-history MCP server with a synced database. Accept the operational cost; understand it's not officially supported
The mistake is trying to make Claude Code's local JSONLs portable directly. They're not designed for it; the workarounds are unreliable; the better answer is to capture continuity at the workspace layer where everything else already lives.