Session Versioning

Every time you push a session, CodeTeleport creates a new version rather than overwriting the previous one. This means you can roll back to an earlier state if needed.

How it works

First push creates version 1
Each subsequent push of the same session creates the next version (v2, v3, …)
When the version limit is reached, the oldest version is auto-deleted to make room

Version numbers are cumulative — if v1 is deleted by auto-rotation and you push again, the new version is v4 (not v1 again).

Version limits

Plan	Versions per session
Free	2
Pro	10

See Plans & Limits for full plan details.

Viewing versions

CLI

$ codeteleport versions c3a05473-9f12-4a2b-ae27-9478ab66d216

Session c3a05473
  Version limit: 2 (free plan)

  Version  Size      Pushed
  v3       13.7 MB   Apr 2, 02:06 PM  (latest)
  v2       13.3 MB   Apr 1, 11:06 AM

  Pull a specific version:
    codeteleport pull --session-id c3a05473 --version 2

MCP

Say to Claude Code:

“Show me the versions of this session”

This calls the teleport_versions tool. See MCP Tools for details.

Pulling a specific version

By default, codeteleport pull downloads the latest version. To pull an older version:

codeteleport pull --session-id c3a05473 --version 2

The MCP teleport_pull tool also accepts an optional version parameter.

Auto-rotation

When you push and the version count would exceed your plan’s limit, the oldest version is automatically deleted — both the database record and the R2 storage object. You don’t need to manage versions manually.

For example, on the free plan (limit: 2):

Push v1 → [v1]
Push v2 → [v1, v2]
Push v3 → [v2, v3]  ← v1 auto-deleted
Push v4 → [v3, v4]  ← v2 auto-deleted

Plan downgrade

If you downgrade from Pro to Free, your excess versions are trimmed to the free plan limit (2) when the downgrade webhook fires. The newest versions are kept, oldest are deleted.

Cloud list

Sessions with multiple versions show version info in the cloud list:

  1) my-project  a1b2c3d4  work-laptop  5.3 MB  v3 (3)

v3 (3) means the current version is 3 and there are 3 versions total. Single-version sessions show no version indicator.