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 Claude Code sessions found for this directory.”

You ran codeteleport push from a directory that has no Claude Code sessions. Make sure you’re in the project root where you’ve used Claude Code:

cd /path/to/your/project
codeteleport push

You can check what sessions exist locally:

codeteleport list --local

“Could not detect current session.”

The CLI couldn’t find a running Claude Code session in the process tree. This happens when you’re running codeteleport push from a regular terminal (not inside Claude Code). The CLI will fall back to scanning the current directory for sessions.

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	Not supported	Path detection assumes Unix-style paths (`/Users/`, `/home/`). Planned for future.

FAQ

Can I use CodeTeleport with Cursor, Windsurf, or other AI coding tools?

Not yet — CodeTeleport currently supports Claude Code only. The MCP server follows the standard Model Context Protocol, so it may work with other MCP-compatible agents. We plan to add official support for more tools in the future. 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 local ~/.claude/ directory
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 Claude Code data?

No. CodeTeleport reads from ~/.claude/ to scan and bundle sessions, but it never writes to or modifies that directory. When you pull a session, it’s installed into ~/.claude/projects/ using Claude Code’s standard file format, but only for the pulled session — your other sessions are untouched.

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 Claude Code:

claude mcp remove codeteleport