codeteleport pull

Synopsis

codeteleport pull [--session-id <id>] [--version <n>] [--target-dir <path>] [--machine <name>] [--agent <id>] [--all] [--as <id>]

Description

The pull command downloads a session from CodeTeleport cloud storage and installs it into the local data directory of the AI coding agent that produced it. After installation, resume with the command shown in the output — claude --resume <id> for Claude Code, codex resume <id> for Codex, or agy --conversation <id> for Antigravity.

The install destination depends on the bundle’s agent, not your local config: Claude Code restores to ~/.claude/projects/, Codex to ~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<id>.jsonl, and Antigravity to ~/.gemini/antigravity-cli/conversations/<id>.db.

If no --session-id is provided, the command fetches your cloud sessions and presents an interactive picker. The picker defaults to your configured agent’s sessions (each row is labelled with its agent); use --all to browse every agent or --agent <id> to pick a specific one. Pulling a specific session by --session-id always works regardless of agent. You always see a confirmation before any download starts.

During installation, all paths inside the session are automatically rewritten to match the current machine’s username and directory structure. A session pushed from /Users/alice/workspace/myapp on one machine will be correctly mapped to /Users/bob/projects/myapp on another. See Path Rewriting for how this works.

Note

The resume command and install location are determined by the agent that created the bundle (recorded in the bundle’s meta.json agentId), not the agent this machine is configured for. A bundle made by one agent restores and resumes correctly even on a machine set up for a different agent. Legacy bundles with no recorded agent are treated as Claude Code (claude-code).

Flags

Flag	Description
--session-id <id>	Pull a specific session by ID instead of browsing the list.
--version <n>	Pull a specific version instead of the latest. Use with --session-id. See codeteleport versions.
--target-dir <path>	Anchor the session at this directory. Defaults to the current working directory. This is the project root that paths will be rewritten relative to.
--machine <name>	Filter the session list to only show sessions pushed from a specific machine.
--agent <id>	Scope the picker list to a specific agent (claude-code, codex, or antigravity). Defaults to your configured agent. Does not restrict --session-id pulls.
--all	Show sessions from all agents in the picker, overriding the default per-agent scope.
--as <id>	Convert the session into another agent’s format on install: claude-code, codex, or antigravity. See Converting between agents.

Converting between agents

By default pull restores a session for the agent that created it. With --as you can instead convert it into a different agent’s format on the way in:

# pull a Codex chat and continue it in Claude Code
$ codeteleport pull --session-id a1b2c3d4 --as claude-code

# pull a Claude Code chat and continue it in Codex
$ codeteleport pull --session-id a1b2c3d4 --as codex

# pull a Claude Code (or Codex) chat and continue it in Antigravity
$ codeteleport pull --session-id a1b2c3d4 --as antigravity

Conversion works between any two agents — Claude Code, Codex, and Antigravity all convert to each other.

Caution

Conversion is transcript-level: the conversation history (your prompts and the agent’s replies) carries over so you can pick up the thread in the other agent, but file-history snapshots, exact tool-call fidelity, and agent-specific sidecar state do not. Converting to Codex needs Codex to have run once on the machine (so ~/.codex/state_5.sqlite exists). Converting to Antigravity synthesizes a fresh conversation database from the transcript (the original tool steps and per-call metadata are not reconstructed). Omit --as to restore natively with full fidelity.

Examples

Interactive pull (browse cloud sessions)

$ codeteleport pull

Cloud sessions (5 of 12):

  1) api-refactor   a1b2c3d4  work-laptop     847 KB   10 min ago
  2) auth-bug-fix   f9e8d7c6  work-laptop    1203 KB   2 hours ago
  3) dashboard-ui   b5a4c3d2  home-desktop    512 KB   1 day ago
  4) api-refactor   c7d8e9f0  work-laptop     934 KB   3 days ago
  5) docs-update    d1e2f3a4  home-desktop    289 KB   1 week ago

Pick a session (number): 1

Downloading...
Installing...

Session pulled
  id      : a1b2c3d4-e5f6-7890-abcd-ef1234567890
  version : 3
  from    : work-laptop
  to   : /Users/bob/.claude/projects/-Users-bob-workspace-api

Resume with: claude --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890

Pull a specific session

$ codeteleport pull --session-id a1b2c3d4-e5f6-7890-abcd-ef1234567890
Downloading...
Installing...

Session pulled
  id      : a1b2c3d4-e5f6-7890-abcd-ef1234567890
  version : 3
  from    : work-laptop
  to   : /Users/bob/.claude/projects/-Users-bob-workspace-api

Resume with: claude --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890

Pull into a specific directory

$ codeteleport pull --target-dir ~/projects/api-service
Downloading...
Installing...

Session pulled
  id      : a1b2c3d4-e5f6-7890-abcd-ef1234567890
  version : 3
  from    : work-laptop
  to   : /Users/bob/.claude/projects/-Users-bob-projects-api-service

Resume with: claude --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890

Filter by source machine

$ codeteleport pull --machine home-desktop

Cloud sessions (2 of 2):

  1) dashboard-ui   b5a4c3d2  home-desktop   512 KB   1 day ago
  2) docs-update    d1e2f3a4  home-desktop   289 KB   1 week ago

Pick a session (number):

Output for other agents

The examples above show Claude Code output. When the bundle was created by a different agent, the to line and the resume command change to match that agent. For a Codex bundle:

Session pulled
  id      : a1b2c3d4-e5f6-7890-abcd-ef1234567890
  version : 3
  from    : work-laptop
  to   : /Users/bob/.codex/sessions/2026/06/17/rollout-2026-06-17T10-30-00-a1b2c3d4-e5f6-7890-abcd-ef1234567890.jsonl

Resume with: codex resume a1b2c3d4-e5f6-7890-abcd-ef1234567890

For an Antigravity bundle:

Session pulled
  id      : a1b2c3d4-e5f6-7890-abcd-ef1234567890
  version : 3
  from    : work-laptop
  to   : /Users/bob/.gemini/antigravity-cli/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890.db

Resume with: agy --conversation a1b2c3d4-e5f6-7890-abcd-ef1234567890

Tip

After pulling, cd into your project directory and run the resume command shown in the output (claude --resume for Claude Code, codex resume for Codex, agy --conversation for Antigravity). Your agent picks up the full conversation context — messages and tool calls — exactly where you left off.

What happens during pull

1. Download — the compressed session bundle is fetched from cloud storage to a temporary file.
2. Unbundle — the archive is extracted and session files are written into the agent’s local data directory: ~/.claude/projects/ for Claude Code, ~/.codex/sessions/... (plus the state_5.sqlite thread inventory) for Codex, and ~/.gemini/antigravity-cli/ for Antigravity.
3. Path rewriting — all absolute paths in the session data (working directory, file references, tool call arguments) are rewritten from the source machine’s paths to the current machine’s paths. For Claude Code and Codex transcripts and memory, this is text replacement. For Antigravity, the conversation is a SQLite database whose payloads are protobuf BLOBs, so embedded absolute paths are rewritten with binary, length-prefix-aware protobuf rewriting across the whole database (field-length prefixes are recomputed so message framing stays valid), plus text rewriting of the brain folder. See Path Rewriting.
4. Restore sidecars — for Claude Code, project memory is restored under the target project and any included extra files are written to their path-rewritten targets (see below). For Codex, the rollout transcript and thread inventory are restored. For Antigravity, the conversation DB and brain folder are restored.
5. Cleanup — the temporary download file is removed.

Caution

For Codex, pull 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.

Note

For Claude Code, pull also restores project memory and any extra working files that were bundled with push --include. Memory uses a merge policy: MEMORY.md is unioned line-by-line (order preserved, duplicates dropped) and other existing memory files are never overwritten — your local memory edits are safe. Extra files use an overwrite policy. Both are guarded by restore-safety: a file is only written if its rewritten target stays inside the target project, the agent’s data directory, or a temp root and isn’t a sensitive path — anything else is skipped.

Project memory is a Claude-Code-only concept. Codex restores its rollout transcript plus the thread inventory (not memory), and Antigravity restores its conversation SQLite DB plus the ~/.gemini/antigravity-cli/brain/<id>/ folder (transcripts, artifacts, scratch — text files are path-rewritten).

Note

Restoring Codex and Antigravity session state uses the built-in node:sqlite module, so the CLI requires Node.js >= 22.5.0 (macOS, Linux, and Windows). See the installation guide.

Related commands

• codeteleport push — push a session to the cloud
• codeteleport list --cloud — browse cloud sessions without pulling
• codeteleport delete — remove a session from the cloud