Troubleshooting

Common Errors

”Not logged in. Run `codeteleport auth login` first.”

Your CLI config file is missing. You need to authenticate:

codeteleport auth login

See Authentication for details.

”Config file is corrupted.”

The file at ~/.codeteleport/config.json is unreadable. Re-authenticate to fix it:

codeteleport auth login

“No coding sessions found for this directory.”

You ran codeteleport push from a directory that has no coding sessions for your configured agent. Make sure you’re in the project root where you’ve used your AI coding agent (Claude Code, Codex, or Antigravity):

cd /path/to/your/project
codeteleport push

push scans the agent set in your config, so the configured agent must match the sessions you expect to find. If you used a different agent in this directory, switch first:

codeteleport config set agent <claude-code|codex|antigravity>

You can check what sessions exist locally:

codeteleport list --local

“Could not detect current session.”

The CLI couldn’t detect a running coding session. This happens when you’re running codeteleport push from a regular terminal (not inside your AI coding agent). Detection differs per agent: Claude Code uses the process tree, while Codex and Antigravity detect the active session from their local session history rooted at the current directory. When detection fails, the CLI falls back to scanning the current directory for sessions — this applies to all agents.

If no sessions are found, use --session-id to specify one explicitly:

codeteleport push --session-id c3a05473

“Session already exists” (409 Conflict)

This means a confirmed session with the same ID already exists in the cloud. The MCP tools handle this by auto-overwriting. If you see this from the CLI, the session may belong to a different account.

”Plan limit reached” (403 Forbidden)

You’ve hit your plan’s session or device limit. Options:

Delete old sessions: codeteleport delete <session-id>
Remove unused devices from the dashboard
Upgrade to Pro

”Upload failed: 403 Forbidden”

The presigned upload URL was rejected by cloud storage. This usually means:

The R2 API token doesn’t have permission for the bucket (development setup issue)
The presigned URL expired (they last 5 minutes)

Try pushing again. If the issue persists, re-authenticate with codeteleport auth login.

”Authentication failed”

Your GitHub OAuth or email/password login failed. For GitHub OAuth:

Make sure you authorized the correct GitHub account
If the browser shows “connection refused”, the CLI’s local callback server may have timed out — try again

For email/password:

Check your email and password
Use --register if you need to create a new account

Platform Notes

Platform	Status	Notes
macOS	Fully supported	Primary development platform
Linux	Fully supported	Tested on Ubuntu, Debian
Windows	Fully supported	Native Windows support — no WSL required. Cross-OS path rewriting handles drive letters (`C:\Users\…`), backslash separators, and case-insensitive paths, so a session pushed from Windows restores on macOS/Linux and vice versa. Config lives at `%USERPROFILE%\.codeteleport\config.json`.

FAQ

Can I use CodeTeleport with other AI coding tools?

CodeTeleport supports three AI coding agents: Claude Code (id claude-code, the default), Codex (OpenAI, id codex), and Antigravity (Google, id antigravity). Choose interactively with codeteleport setup, which lists all supported agents, or directly with codeteleport config set agent <claude-code|codex|antigravity>.

Those three are the officially supported agents. The MCP server also follows the standard Model Context Protocol, so it may work with other MCP-compatible agents, though only the three above are officially supported. See MCP Setup for details.

Is my data encrypted?

In transit: Yes — all API calls and uploads use HTTPS (TLS 1.2+)
At rest: Yes — Cloudflare R2 encrypts stored bundles
End-to-end: Not yet — client-side encryption (AES-256-GCM) is planned

See the Security page for full details.

Can I self-host CodeTeleport?

The MCP package is open source. The API and infrastructure are documented in the repo. There’s no official self-hosting guide yet, but contributions are welcome.

What happens if I cancel my Pro subscription?

You’re downgraded to Free plan limits. Your existing sessions and devices are kept — you just can’t create new ones beyond the limits (25 sessions, 3 devices). You can still pull and delete existing sessions.

Can I use CodeTeleport offline?

codeteleport list --local works offline — it scans your configured agent’s local session directory (~/.claude/projects for Claude Code, ~/.codex/sessions for Codex, ~/.gemini/antigravity-cli/conversations for Antigravity)
codeteleport push, pull, list --cloud, and status require an internet connection

How large are session bundles?

Typical sizes:

Session length	Bundle size
Short (< 100 messages)	10–100 KB
Medium (100–1000 messages)	100 KB – 2 MB
Long (1000+ messages)	2–50 MB

Bundles are compressed .tar.gz files. The largest component is usually the JSONL conversation log.

Does CodeTeleport modify my local agent data?

No. CodeTeleport reads from your agent’s data directory to scan and bundle sessions, but it never writes to or modifies your existing sessions. When you pull a session, it installs only that one session into the agent’s directory using the agent’s native format:

Claude Code — ~/.claude/projects/<encoded-cwd>/<id>.jsonl (plus its sidecars)
Codex — ~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<id>.jsonl for the transcript, plus an upserted thread-inventory row in ~/.codex/state_5.sqlite so codex resume <id> can find the session
Antigravity — ~/.gemini/antigravity-cli/conversations/<id>.db and ~/.gemini/antigravity-cli/brain/<id>/

Your other sessions are untouched.

I pulled a Codex session but `codex resume` can’t find it

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.

Uninstall

To completely remove CodeTeleport:

Delete your account (optional) — go to app.codeteleport.com and delete your account from the settings page, or cancel your subscription first via billing.
Remove the CLI config:

rm -rf ~/.codeteleport

Uninstall the npm package:

npm uninstall -g codeteleport

Remove the MCP server from your agent — run the command matching your configured agent:

claude mcp remove codeteleport   # Claude Code
codex mcp remove codeteleport    # Codex
agy mcp remove codeteleport      # Antigravity

Still need help?

If your issue isn’t covered above, reach out:

Support: support.codeteleport.com — docs, Discord, and contact info
GitHub Issues: Open an issue to report bugs or request features
Discord: Join our community to ask questions or report bugs in #bugs