session-teleport

Session Teleport — handoff operators for Claude Code workflows

Move an active Claude Code workflow between machines without losing the thread.

Start on machine A. Continue on machine B. Keep session continuity instead of re-prompting the whole workflow.

Problem / JTBD

Claude Code sessions are stateful. Copying source files is not enough when the thing you want to move is the active workflow itself: the session log, sidecar artifacts, and the point in the conversation where work is already underway.

Session Teleport packages that handoff into a single Claude Code skill. It is built for the common loop of planning locally, launching remotely for long-running work, checking progress later, and pulling the resulting forked session back to your original machine.

What It Is

• A Claude Code plugin that exposes a /remote skill with launch, pull, list, check, and doctor
• A config-driven handoff layer over SSH, SCP, tmux, and Claude Code session bundles
• A way to move session continuity between machines that already have access to the same repo

What It Isn't

• Not file sync
• Not live process migration
• Not Claude Remote Control itself
• Not cloud execution or a hosted service

Install

Plugin install:

claude plugin install github:zongmin-yu/session-teleport

Manual install:

cp -r skills/remote ~/.claude/skills/
mkdir -p ~/.config/session-teleport
cp examples/clusters.json ~/.config/session-teleport/clusters.json

Project-local config is also supported. If you want the cluster map to live with a repo, create .claude/remote-clusters.json in that project and it will take precedence over the user-level config.

Flows

Launch the current session onto a remote machine:

/remote launch my-gpu-server "finish the training run and summarize results"

Check whether the remote tmux session is still active:

/remote check my-gpu-server

Pull the newest forked session back to local storage:

/remote pull my-gpu-server

Inspect all configured machines:

/remote list

Run preflight and environment checks:

/remote doctor

Configuration

The cluster registry is resolved in this order:

1. .claude/remote-clusters.json
2. ~/.config/session-teleport/clusters.json

Example:

{
  "my-gpu-server": {
    "ssh_alias": "gpu-server",
    "repo_base": "/home/username/repos",
    "claude_projects": "/home/username/.claude/projects",
    "project_slug": "auto",
    "default_cwd": "/home/username/repos/my-project"
  }
}

project_slug: "auto" tells the skill to derive the remote Claude project slug from default_cwd by replacing / with -. If your remote Claude storage already uses a fixed slug, set that string explicitly instead.

Launch history is recorded in .claude/remote-sessions.json inside the current project so you can trace which source session was launched, which tmux session was created, and which pulled session came back later.

Safety

Session Teleport assumes you trust the remote machine you are targeting. It copies Claude session artifacts with scp, starts Claude under tmux, and may use --dangerously-skip-permissions on the remote side because unattended remote work otherwise stalls on permission prompts.

That means:

• You should only target machines you administer or explicitly trust
• Source code sync remains your responsibility
• Shell state, virtualenv state, port forwards, and live MCP connections do not teleport
• Remote Control is optional and feature-detected; if the CLI does not advertise --rc, attach and run /rc manually

Under The Hood

The skill treats a Claude Code session bundle as:

• ~/.claude/projects/<project-slug>/<session-id>.jsonl
• Optional sibling directory ~/.claude/projects/<project-slug>/<session-id>/

/remote launch finds the newest local bundle for the current repo, copies it to the configured remote Claude project directory, resumes it with claude --resume <session-id> --fork-session, and records metadata locally. /remote pull copies the resulting remote fork back into the local project store so you can resume it again from your original machine.

This keeps the abstraction focused: move the workflow, not just the files.