Uncovering Claude Code's Hidden --teleport Flag

I've been working on an AST graph analysis of Claude Code's cli.js in my free time, and recently I stumbled upon something I have not seen mentioned anywhere on the internet: fully implemented remote session storage features hidden behind undocumented flags. At a later date I can write more about my process, but for now, here’s what I was able to ascertain buried in the AST:

• --remote <description> - Creates sessions on claude.ai servers instead of local storage

• --teleport [session] - Resumes remote sessions from any machine (interactive or direct mode)

Instead of sessions being tied to ~/.claude/{projects,todos, etc...}, you get cloud-synced sessions with shareable URLs.

Unsurprisingly, attempting to use these options results in an error:

claude --remote "Implementing OAuth2 authentication"
Error: Unable to create remote session

But that doesn't mean the fun stops here. The exact output strings are embedded in the source, and analyzing the obfuscated AST's control flow graph reveals the underlying behavior patterns, letting us speculate about what this will look like when released.

What --remote Actually Does

claude --remote "Implementing OAuth2 authentication"
Created remote session: Implementing OAuth2 authentication
View: https://claude.ai/code/550e8400-e29b-41d4-a716-446655440000?m=0
Resume with: claude --teleport 550e8400-e29b-41d4-a716-446655440000

Sessions are stored on claude.ai and all messages are synced automatically.

Resuming a Remote Session

Teleport supports two modes:

Interactive selector

--teleport with no args:

claude --teleport

Fires telemetry event tengu_teleport_interactive_mode, then displays a filterable session list. If you're in a git repo, it automatically filters to show only sessions from that repo, preventing accidental cross-project contamination.

Direct resume

--teleport <id>:

claude --teleport 550e8400-e29b-41d4-a716-446655440000

Fetches conversation history from claude.ai and resumes locally. Repository validation is enforced and throws an error if current repo doesn't match session metadata:

Authentication Required

Remote sessions require OAuth tokens from claude.ai. The code explicitly blocks:

• ANTHROPIC_API_KEY (shows error: "Remote sessions require claude.ai account")

• CLAUDE_CODE_USE_BEDROCK environment variable

• CLAUDE_CODE_USE_VERTEX environment variable

Accepted auth sources:

• ANTHROPIC_AUTH_TOKEN

• CLAUDE_CODE_OAUTH_TOKEN

Implementation Details

Here are some of the key functions:

• createRemoteSessionAPI() - Creates session via claude.ai API

• aI1() - Main teleport entry point

• r4Q() - Interactive session selector with keyboard nav

• LJB() / MJB() - Dual API implementation (new Sessions API vs. legacy)

The codebase uses two different API versions based on a feature flag check. Session metadata includes:

{
  id: uuid,
  title: string,
  updated_at: timestamp,
  repo: { owner, name },
  branch: string,
  log: /* conversation history */
}

No device-specific data is stored; sessions are purely remote state with OAuth-based access from any location. Notably, this differs from other applications with cross-device workflows (e.g. syncthing) that have explicit multi-device syncing.

Telemetry Events

Every remote operation emits specific events:

• tengu_remote_create_session_success - Session creation

• tengu_teleport_interactive_mode - Interactive selector shown

• tengu_teleport_resume_session - Session resumed

• tengu_teleport_cancelled - User cancelled selection

Background Task Integration

Remote sessions integrate with Claude's background task system (cli.js line 3193). When you run a long task in the background, the output includes:

Monitor it with /tasks or at https://claude.ai/tasks/<task-id>.

Or, resume it later with: claude --teleport <session-id>

The evidence suggests cross-device workflows (start on laptop, resume on desktop) or possibly remote agents running tasks server-side. Let me know if you have an idea.

Custom Headers

The code checks for TELEPORT_HEADERS environment variable (cli.js line 2839):

export TELEPORT_HEADERS='{"X-Header-Name": "true"}' # idk
claude --teleport abc-123-def

Parsed as JSON and included in API requests. Maybe related to enterprise features?

Additional Info

• Requires internet connectivity

• Strict repository validation (throws error on mismatch)

• OAuth authentication required

• Local MCP servers don't sync

• Likely account-locked (no cross-account transfer mechanism visible)

• No client-side expiration logic (server-side retention unknown)

---

One last speculation I will make is that these discoveries suggest Anthropic is preparing for enterprise-grade collaborative features in Claude Code, and it may even be only for enterprise with the extent that Anthropic is catering Claude Code to Enterprise customers. Maybe I should figure out how to switch myself to an enterprise plan...