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.

Note

CodeTeleport supports three AI coding agents — Claude Code (id claude-code, default), Codex (OpenAI, id codex), and Antigravity (Google, id antigravity). Choose your agent interactively with codeteleport setup (it lists all supported agents from the registry) or directly with codeteleport config set agent <claude-code|codex|antigravity>. Claude Code is used as the primary example throughout this page, with the Codex and Antigravity equivalents called out alongside it.

What gets bundled

When you push a session, CodeTeleport collects everything your agent stores for that conversation. The exact contents differ per agent — bundling is dispatched per-agent — so each agent has its own breakdown below. All of these are collected into a single .tar.gz bundle for upload.

Claude Code

Component	Description
session.jsonl	The main conversation log — every message, tool call, and response in JSON Lines format
Subagent conversations	If Claude spawned background agents during the session, their JSONL logs are included
File history	Snapshots of files that Claude read or edited, stored under ~/.claude/file-history/<session-id>/
Paste cache	Content you pasted into the conversation
Shell snapshots	Terminal state captured during the session
Session environment	Environment metadata stored under ~/.claude/session-env/<session-id>/
Project memory (new in 0.3.0)	Claude’s memory for the project, stored under ~/.claude/projects/<encoded-path>/memory/
Extra working/temp files (new in 0.3.0)	Files edited during the session, plus any extra paths you opt in to including

Subagent conversations, paste cache, session environment, file history, and project memory are Claude-Code-specific — Codex and Antigravity bundles do not include them.

Codex

Component	Description
session.jsonl	The rollout transcript, sourced from ~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<id>.jsonl
codex-state.json	Restore-only thread-inventory state captured from ~/.codex/state_5.sqlite, used to re-register the thread on pull
Extra working/temp files	Any extra paths you opt in to including with --include

Auto-detection of edited files is apply_patch-only — files changed via the shell (exec_command) are opaque, so use --include for those. Codex shell-snapshot capture is opt-in (excluded by default, since snapshots may contain secrets).

Antigravity

Component	Description
session.db	The conversation SQLite database (conversations/<id>.db) — this DB is the session; its payloads are protobuf
brain/	The brain/<id>/ folder: transcripts, artifacts, and scratch state
Extra working/temp files	Any extra paths you opt in to including with --include

Antigravity has no edited-file auto-detection — use --include for any working or temp files you want to travel with the session.

Project memory (Claude Code)

Project memory is a Claude-Code-only feature — Codex and Antigravity do not bundle a separate project-memory directory.

If the project memory directory at ~/.claude/projects/<encoded-path>/memory/ contains at least one file, it is bundled along with the session. An empty memory directory is treated as no memory.

On pull, memory is restored under the target project’s memory/ directory, and .md contents are path-rewritten for the new machine. The default conflict policy is merge:

• MEMORY.md is union-merged line by line — order is preserved, duplicate lines are dropped, and the trailing newline is kept.
• Other existing memory files are never overwritten. They are kept if already present, and written only if absent.

Extra working and temp files

CodeTeleport can include extra files alongside the session. How files are auto-included depends on the agent, and --include is the universal explicit mechanism for any agent:

• Claude Code auto-includes files it edited via Edit/Write during the session.
• Codex auto-detects only apply_patch edits — shell (exec_command) edits are opaque, so use --include for those.
• Antigravity has no edited-file auto-detection — use --include for any working or temp files.

You can opt in to more files with either interface:

• CLI: codeteleport push --include <paths> — comma-separated and repeatable. Relative paths resolve against the session cwd.
• MCP: teleport_push with includePaths — an array of absolute paths.

Files are filtered before bundling. Only paths under an allowlist root are eligible — the session cwd, the system temp directory, /tmp, and /private/tmp. A sensitive deny-list is never bundled:

• Directories: ~/.ssh, ~/.aws, ~/.config, ~/.gnupg
• Filenames: *.pem, *.key, *.p12/.pfx/.pkcs8/.p8/.jks/.keystore, .env*, id_rsa/id_dsa/id_ecdsa/id_ed25519, .netrc, .npmrc, credentials

Credential stores are never bundled — auth.json, ~/.ssh, ~/.aws, *.pem/*.key, .env*, id_rsa, .npmrc, .netrc, credentials, and Codex logs/memories DBs — and project source code does not travel except via --include. Only agent session state plus explicit --include files leave your machine.

Size caps apply: 25 MB per file and 100 MB total. Symlinks are dereferenced, and any file already captured as part of the session is de-duplicated.

On pull, each extra file is restored to its path-rewritten target with the default policy overwrite — but only if the resolved target stays inside the target project cwd, its .claude directory, or a temp root, and is not sensitive. Targets that fail this restore-safety check are skipped.

Where sessions live locally

Each agent stores its sessions in its own location and layout.

Claude Code

Claude Code stores sessions on disk at:

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

The <encoded-cwd> 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, session environment, paste cache, shell snapshots, and project memory are stored in sibling directories under ~/.claude/.

Codex

Codex stores the rollout transcript in a date-bucketed path, plus a thread-inventory row in a state database:

~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<id>.jsonl   # transcript
~/.codex/state_5.sqlite                                 # thread inventory

Codex does not dash-encode the project directory.

Antigravity

Antigravity stores the conversation as a SQLite database plus a brain/ folder:

~/.gemini/antigravity-cli/conversations/<id>.db   # SQLite DB whose payloads are protobuf — the DB IS the session
~/.gemini/antigravity-cli/brain/<id>/             # transcripts, artifacts, scratch

Antigravity does not dash-encode the project directory.

Tip

Use teleport_local_list (or codeteleport list --local) to scan your local sessions without needing cloud access. It scans whichever agent you have configured. See MCP Tools for details.

Session ID

Every session has a UUID assigned by your agent (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, CodeTeleport preserves it so the agent’s resume command works:

• Claude Code: claude --resume <id>
• Codex: codex resume <id>
• Antigravity: agy --conversation <id>

The resume command shown on pull is derived from the bundle’s recorded agent (meta.json agentId), not the puller’s local config — so a bundle made by one agent resumes correctly even on a machine configured for a different agent.

Converting between agents

By default a session restores for the agent that created it. You can also convert it on pull with codeteleport pull --as <claude-code|codex|antigravity> — e.g. continue a Codex chat in Claude Code, or a Claude Code chat in Antigravity. Conversion works between any two agents. It is transcript-level: the conversation carries over, but file history, tool-call fidelity, and agent-specific sidecars do not. Converting to Antigravity synthesizes a fresh conversation database from the transcript.

Bundle format

The uploaded bundle is a gzipped tar archive (.tar.gz). Every bundle contains a meta.json, but the rest of the layout differs per agent.

The meta.json file records the bundle’s agentId and formatVersion (making the bundle self-describing), along with the source machine’s user directory and working directory, plus checksums. The source directories drive path rewriting on pull. Legacy bundles without an agentId are treated as claude-code.

A bundle always restores under its own recorded agent, even if the target machine is configured for a different agent.

Claude Code layout

meta.json            # agentId, formatVersion, 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
memory/              # project memory (if any)        -- new in 0.3.0
extra-files/         # included working/temp files     -- new in 0.3.0

Codex layout

meta.json                    # agentId, formatVersion, source paths, checksums
session.jsonl                # rollout transcript
codex-state.json             # restore-only thread-inventory state
extra-files-manifest.json    # included working/temp files

Antigravity layout

meta.json                    # agentId, formatVersion, source paths, checksums
session.db                   # conversation SQLite DB (payloads are protobuf)
brain/                       # transcripts, artifacts, scratch
extra-files-manifest.json    # included working/temp files

Self-describing bundles and restore behavior

Because meta.json records the agentId, a bundle made by one agent restores correctly regardless of the target machine’s configured agent.

• Codex: On pull, Codex writes the rollout transcript AND upserts the thread-inventory row in ~/.codex/state_5.sqlite so codex resume <id> finds the session. If state_5.sqlite does not exist yet on the target machine, the transcript is still restored but the thread row is not — run Codex once, then re-pull.
• Antigravity: Restore rewrites absolute paths inside the protobuf BLOBs across the whole conversation SQLite DB (binary, length-prefix-aware rewriting), plus the brain/ text files. See Path Rewriting for the text-vs-binary detail.

Note

Codex and Antigravity support require Node.js >= 22.5.0 (the CLI uses the built-in node:sqlite module to read and write their session state databases). node:sqlite is cross-platform, so this works on macOS, Linux, and Windows. See setup for full requirements.

Related

• Push a session — CLI reference for uploading
• Pull a session — CLI reference for downloading and installing
• Path Rewriting — how paths are translated between machines
• MCP Setup — agent selection (codeteleport config set agent <id>) and requirements