Skip to content
CodeTeleport

Sessions

A session is a single AI coding conversation — the back-and-forth exchange between you and your coding agent. CodeTeleport packages that conversation and moves it between machines.

What gets bundled

Section titled “What gets bundled”

When you push a session, CodeTeleport collects everything Claude Code stores for that conversation:

ComponentDescription
session.jsonlThe main conversation log — every message, tool call, and response in JSON Lines format
Subagent conversationsIf Claude spawned background agents during the session, their JSONL logs are included
File historySnapshots of files that Claude read or edited, stored under ~/.claude/file-history/<session-id>/
Paste cacheContent you pasted into the conversation
Shell snapshotsTerminal state captured during the session
Session environmentEnvironment metadata stored under ~/.claude/session-env/<session-id>/

All of these are collected into a single .tar.gz bundle for upload.

Where sessions live locally

Section titled “Where sessions live locally”

Claude Code stores sessions on disk at:

~/.claude/projects/<encoded-path>/<session-id>.jsonl

The <encoded-path> is your project directory with slashes replaced by dashes. For example, if you are working in /Users/alice/projects/billing-api, the encoded path is -Users-alice-projects-billing-api, and a session file might be:

~/.claude/projects/-Users-alice-projects-billing-api/c3a05473-9f12-4a2b-ae27-9478ab66d216.jsonl

Subagent conversations, file history, and other artifacts are stored in sibling directories under ~/.claude/.

Session ID

Section titled “Session ID”

Every session has a UUID assigned by Claude Code (e.g. c3a05473-9f12-4a2b-ae27-9478ab66d216). CodeTeleport uses this ID as-is — it does not generate its own identifiers. When you pull a session onto a new machine, the same UUID is preserved so claude --resume <id> works.

Bundle format

Section titled “Bundle format”

The uploaded bundle is a gzipped tar archive (.tar.gz) containing:

meta.json            # session metadata (ID, source paths, checksums)
session.jsonl        # main conversation log
session-subdir/      # subagent conversations (if any)
file-history/        # file snapshots
session-env/         # environment metadata
paste-cache/         # pasted content
shell-snapshots/     # terminal state

The meta.json file records the source machine’s user directory and working directory, which CodeTeleport uses during path rewriting on pull.

Section titled “Related”