codeteleport push

Synopsis

codeteleport push [--session-id <id>] [--label <text>] [--tags <tags>] [--include <paths>] [--silent]

Description

The push command bundles an AI coding session (messages, file history, tool calls) into a compressed archive and uploads it to CodeTeleport cloud storage.

Session detection follows this priority:

1. Explicit --session-id — looks up the given ID in your configured agent’s local session data under the current directory.
2. Auto-detection — if you’re running codeteleport push from inside an AI coding session (e.g. via a tool call or shell escape), the session is detected automatically. The mechanism differs by agent: Claude Code uses the parent process tree (the working directory is taken from the detected session); Codex and Antigravity resolve the active session from the agent’s local data rooted at the current directory.
3. Local scan with interactive picker — scans the current directory for sessions in your configured agent’s local store (Claude Code: ~/.claude/projects/; Codex: ~/.codex/sessions/; Antigravity: ~/.gemini/antigravity-cli/conversations/). If multiple sessions exist, you pick from a numbered list.

Before uploading, the command prints a summary of the session being pushed so you can confirm it’s the right one.

Tip

To understand what gets bundled (and what doesn’t), see Sessions.

Flags

Flag	Description
--session-id <id>	Push a specific session by ID. Prefix matching is supported — you can pass the first 8 characters. Auto-detection works for any configured agent (Claude Code, Codex, or Antigravity), not just Claude Code — when omitted, the session is detected as described above.
--label <text>	Attach a human-readable label to the session (e.g. "fixing auth bug"). Visible in the dashboard and in codeteleport list --cloud.
--tags <tags>	Comma-separated tags for filtering later (e.g. "wip,auth,backend").
--include <paths>	Extra working/temp files to bundle alongside the session. Comma-separated and repeatable. Relative paths resolve against the session’s working directory. Files the agent edited during the session are usually included automatically — use this for temp files (e.g. a script’s output) that the session touched but didn’t author. Auto-detection varies by agent: Claude Code includes files it edited via Edit/Write; 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 at all, so --include is the only way to bundle working/temp files. --include is the universal explicit mechanism.
--silent	Suppress all output. Useful for auto-sync hooks or scripts where you don’t want terminal noise.

Examples

Push from inside your coding agent (auto-detect)

When your coding agent calls codeteleport push as a tool (e.g. Claude Code, Codex, or Antigravity), the session is detected automatically. The bundle records which agent produced it (meta.json agentId), so it restores and resumes correctly later — even on a machine configured for a different agent:

$ codeteleport push

Pushing session:
  1) api-refactor  a1b2c3d4  12 messages  2 min ago

Bundling...
  size: 847 KB
Uploading...
Confirming...

Session teleported to CodeTeleport
  id      : a1b2c3d4-e5f6-7890-abcd-ef1234567890
  version : 1
  size    : 847 KB
  machine : work-laptop

Push a specific session with label and tags

$ codeteleport push --session-id a1b2c3d4 --label "auth bug fix" --tags "bugfix,auth"

Pushing session:
  1) api-service  a1b2c3d4  28 messages  15 min ago

Bundling...
  size: 1203 KB
Uploading...
Confirming...

Session teleported to CodeTeleport
  id      : a1b2c3d4-e5f6-7890-abcd-ef1234567890
  size    : 1203 KB
  machine : work-laptop

Push with extra working files

Bundle temp files the session produced alongside the session itself. The flag is comma-separated and can be repeated:

$ codeteleport push --include /tmp/data.json,/tmp/report.csv
$ codeteleport push --include /tmp/data.json --include /tmp/report.csv  # equivalent

After bundling, a safety review lists exactly what was included (with sizes) and what was skipped (with a reason):

$ codeteleport push --include /tmp/data.json,/tmp/secret.pem

Bundling...
  size: 901 KB

Included extra files (1):
  /tmp/data.json  4 KB
Skipped (1):
  /tmp/secret.pem  sensitive path
Memory: 2 files bundled

Uploading...
Confirming...

Session teleported to CodeTeleport
  id      : a1b2c3d4-e5f6-7890-abcd-ef1234567890
  version : 3
  size    : 901 KB
  machine : work-laptop

The Memory: line appears only for agents that have project memory (currently Claude Code). For Codex and Antigravity, the safety review shows just the included and skipped extra files.

Caution

When --include is omitted, the CLI prints a note that temp/Bash-created files can’t be auto-detected from the command line. To capture those, re-run push from inside the chat session, or pass them explicitly with --include. Files the agent recorded as edited (and, for Claude Code, your project memory) are bundled either way. Note the per-agent caveat: for Codex only apply_patch edits auto-bundle (shell edits need --include); for Antigravity there is no edited-file auto-detection, so use --include for any working/temp files.

Interactive session picker (multiple sessions in directory)

If multiple sessions exist for the current project and no --session-id is given:

$ codeteleport push

Sessions for ~/workspace/myapp:
  1) myapp  a1b2c3d4  28 messages   15 min ago
  2) myapp  f9e8d7c6  12 messages   2 hours ago
  3) myapp  b5a4c3d2   4 messages   1 day ago

Pick a session (number): 1

Pushing session:
  1) myapp  a1b2c3d4  28 messages  15 min ago

Bundling...
  size: 1203 KB
Uploading...
Confirming...

Session teleported to CodeTeleport
  id      : a1b2c3d4-e5f6-7890-abcd-ef1234567890
  size    : 1203 KB
  machine : work-laptop

Silent mode for automation

$ codeteleport push --silent
# No output. Exit code 0 on success, 1 on failure.

Note

The --silent flag is designed for auto-sync hooks that push sessions on a schedule. Pair it with --session-id for fully non-interactive operation.

What gets uploaded

The bundle includes your configured agent’s full session state for the given session ID. Exact contents depend on the agent:

Claude Code

• the JSONL conversation log (~/.claude/projects/<encoded-cwd>/<id>.jsonl)
• subagent transcripts
• file history (snapshots) and shell snapshots
• session-env and paste-cache
• project memory — the contents of ~/.claude/projects/<encoded-cwd>/memory/, bundled when non-empty

Codex

• the rollout transcript (~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<id>.jsonl)
• the thread-inventory row from ~/.codex/state_5.sqlite, so codex resume <id> finds the session after a pull
• shell snapshots are excluded by default (they may contain secrets)

Antigravity

• the conversation SQLite DB (~/.gemini/antigravity-cli/conversations/<id>.db) — the DB is the session
• its ~/.gemini/antigravity-cli/brain/<id>/ folder (transcripts, artifacts, scratch)

In every case the bundle also includes any extra working files you passed with --include, plus files the agent recorded as edited during the session (see the --include behavior above for the per-agent details). Codex and Antigravity do not have Claude-style subagents, file history, paste-cache, session-env, or a project-memory directory.

It does not include your project source code — only the coding agent’s internal session state and the extra files you explicitly include. The bundle is self-describing (meta.json records agentId and formatVersion), so a session pushed from one agent restores correctly on a machine whose config names a different agent. Paths inside the bundle are rewritten on pull to match the target machine — text-based for Claude Code and Codex transcripts, and binary (protobuf-aware) for Antigravity’s SQLite payloads. See Path Rewriting for details.

Note

Codex first-run gotcha: 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.

Safety review

Every push prints a manifest of what is leaving the machine before it uploads:

• Included extra files — each bundled extra file with its size.
• Skipped files — each rejected path with a reason: not found, not a regular file, outside allowed roots, sensitive path, already in bundle, exceeds per-file size cap, or exceeds total size cap.
• Memory files — the count of project memory files included. This line appears only for agents with project memory (currently Claude Code); Codex and Antigravity bundles omit it.

Extra files are filtered for safety: they must live under an allowed root (the session working directory or a system temp directory), and a deny-list blocks sensitive locations and credential-like files (e.g. ~/.ssh, ~/.aws, *.pem, *.key, .env*, id_rsa) outright. Per-file (25 MB) and total (100 MB) size caps apply, symlinks are dereferenced, and anything already in the session bundle is de-duplicated.

Related commands

• codeteleport pull — download and install a session on another machine
• codeteleport list — browse local and cloud sessions
• codeteleport status — check your usage and remaining session quota