Quick Start

This guide walks through a complete teleport: install CodeTeleport, log in, push a session from your laptop, pull it on your desktop, and resume the conversation.

Note

This walkthrough uses Claude Code as the example agent. CodeTeleport works the same way with Codex and Antigravity — only the per-agent resume command and local storage paths differ. CodeTeleport supports three AI coding agents: Claude Code (id claude-code, the default), Codex (OpenAI, id codex), and Antigravity (Google, id antigravity). Pick yours interactively with codeteleport setup (it lists all supported agents from the registry) or directly with codeteleport config set agent <claude-code|codex|antigravity>.

The scenario

Alice is building my-saas on her work laptop. She’s deep into an AI coding session — refactoring the auth module — and needs to continue on her desktop at home. She’ll push the session from the laptop and pull it on the desktop.

On the laptop (source)

1. Install and log in

   npm install -g codeteleport
   codeteleport auth login

   How do you want to log in?
     1) GitHub
     2) Email & Password
   > 1
   Opening browser for GitHub login...
   
   Logged in via GitHub
   Device: alices-laptop
   API: https://api.codeteleport.com/v1
   Config saved to ~/.codeteleport/config.json

   The agent is selected once via codeteleport setup (which lists all supported agents) or codeteleport config set agent <claude-code|codex|antigravity>. This agent setting controls only what is bundled and scanned locally on push — it does not affect pull, which always uses the bundle’s own recorded agent. Claude Code is the default if you skip this step.

2. Push the session

   From the project directory where your AI coding agent is running:

   cd ~/projects/my-saas
   codeteleport push

   Pushing session:
     1) 2026-03-31 14:22  abc123de  "Refactor auth middleware"  12 messages
   
   Bundling...
     size: 847 KB
   Uploading...
   Confirming...
   
   Session teleported to CodeTeleport
     id      : abc123de-f456-7890-abcd-ef1234567890
     version : 1
     size    : 847 KB
     machine : alices-laptop

   You can optionally add a label and tags to make it easier to find later:

   codeteleport push --label "auth refactor WIP" --tags "auth,refactor"

On the desktop (target)

1. Install and log in (first time only)

   npm install -g codeteleport
   codeteleport auth login --github

   Opening browser for GitHub login...
   
   Logged in via GitHub
   Device: alices-desktop
   API: https://api.codeteleport.com/v1
   Config saved to ~/.codeteleport/config.json

2. Pull the session

   Navigate to the same project (or any directory you want to anchor the session to):

   cd ~/projects/my-saas
   codeteleport pull

   CodeTeleport shows your cloud sessions and lets you pick one:

   Your sessions:
     1) 2026-03-31 14:22  abc123de  alices-laptop  "auth refactor WIP"
     2) 2026-03-28 09:15  def456ab  alices-laptop  "Add billing page"
   
   Select session (1-2): 1
   
   Downloading...
   Installing...
   
   Session pulled
     id   : abc123de-f456-7890-abcd-ef1234567890
     from : alices-laptop
     to   : /Users/alice/projects/my-saas
   
   Resume with: claude --resume abc123de-f456-7890-abcd-ef1234567890

   The resume command shown matches the agent the bundle was created with — claude --resume <id> for Claude Code, codex resume <id> for Codex, agy --conversation <id> for Antigravity. It is derived from the bundle itself (its recorded agent), so a session pushed from one agent always resumes with that agent’s command, even if this machine is configured for a different agent. Legacy bundles with no recorded agent default to Claude Code.

   First time on a new machine with 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.

3. Resume the conversation

   claude --resume abc123de-f456-7890-abcd-ef1234567890

   Your agent picks up exactly where you left off. (Codex and Antigravity resume the same way with their own commands.) All messages, file history, tool calls, and context are intact. File paths have been automatically rewritten from /Users/alice/projects/my-saas on the laptop to the correct path on the desktop.

Tip

If your project lives at different paths on each machine (e.g., ~/projects/my-saas vs ~/dev/my-saas), CodeTeleport handles it automatically. For Claude Code and Codex this is text replacement inside the JSONL transcripts and memory text files; for Antigravity, CodeTeleport rewrites the absolute paths embedded inside the conversation SQLite database as well (binary, length-prefix-aware protobuf rewriting so message framing stays valid). See Path Rewriting to learn how.

What just happened?

1. Push bundled the agent’s full session state (the conversation transcript plus the agent-specific sidecar data), along with your project memory and any extra working/temp files the session touched, into a compressed archive and uploaded it to secure cloud storage. For Claude Code that sidecar data is the subagents, file history, paste cache, shell snapshots, and session env; Codex bundles a rollout transcript plus a thread-inventory row from ~/.codex/state_5.sqlite, and Antigravity bundles a SQLite conversation .db (protobuf payloads) plus a brain/ directory. See Sessions for the per-agent component breakdown.
2. Pull downloaded that archive, unpacked it into your agent’s local session storage (~/.claude for Claude Code, ~/.codex for Codex, ~/.gemini/antigravity-cli for Antigravity), and rewrote all absolute paths so they point to the right locations on the new machine. The install destination and resume command come from the bundle’s recorded agent, not this machine’s local config.
3. Resume told your agent to load the session from its local storage as if it had always been running locally.

To learn more about what’s inside a session bundle, see Sessions.

Next steps

• Configuration — choose your agent (Claude Code, Codex, or Antigravity) and other settings
• Authentication — learn about login methods, API tokens, and configuration
• Sessions — understand what gets bundled and why
• Path Rewriting — how paths are translated across machines