claude-teleport

Move your Claude Code history to a new computer - sessions, memory, and settings - with every path fixed automatically.

Linux · macOS · Windows, in any direction.

If you live in Claude Code, losing your sessions feels like losing part of your workspace.

When I moved from my Linux laptop to a new Mac, I wanted to bring all of it with me: my sessions, conversation history, memory, and project context. There was no clean way to do it. Copying the files by hand is tedious, and because project paths change between machines, nothing just works when you get there.

So I built claude-teleport. It packs your whole Claude Code setup into one file on the old machine and restores it on the new one, rewriting every path so your conversations resume exactly where you left off.

┌─────────────┐    export     ┌───────────────┐   import (paths fixed)   ┌─────────────┐
│ OLD machine │ ────────────▶ │ one .tgz file │ ───────────────────────▶ │ NEW machine │
└─────────────┘               └───────────────┘                          └─────────────┘

Contents

• Why you need it
• Install
• Quick start (5 minutes)
• Prefer clicking? Use the GUI
• Moving between different operating systems
• Command reference
• What gets moved (and what doesn't)
• Is it safe?
• How it works
• FAQ
• Contributing

Why you need it

Copying the ~/.claude folder by hand does not work, for two reasons:

1. Sessions live in folders named after each project's full path, with the slashes turned into dashes (/home/you/app → -home-you-app). That naming is lossy - slashes, dots, underscores and spaces all become - - so you can't reconstruct the real path, and the name is wrong on a machine with a different username or OS anyway.
2. The session files have the old machine's paths written inside them.

claude-teleport handles both: it records each project's true path, then rebuilds the folder names and rewrites the in-file paths for the new machine.

Install

Pick whichever you like.

Option A - Download a ready-made binary (no tools needed)

1. Go to the latest release.
2. Download the file for your computer:

   Your machine	File
   macOS (Apple Silicon)	claude-teleport-darwin-arm64
   macOS (Intel)	claude-teleport-darwin-amd64
   Linux	claude-teleport-linux-amd64
   Windows	claude-teleport-windows-amd64.exe

3. On macOS/Linux, make it runnable and put it on your PATH:
   copy

   chmod +x claude-teleport-*            # allow it to run
   sudo mv claude-teleport-* /usr/local/bin/claude-teleport
   

   On Windows, rename it to claude-teleport.exe and keep it in a folder you can find.

Option B - With Go installed

go install github.com/gowtham-sai-yadav/claude-teleport@latest

This drops the binary in Go's bin directory ($(go env GOPATH)/bin, usually ~/go/bin). If claude-teleport: command not found, that directory is not on your PATH yet. Add it:

# macOS / Linux (zsh)
echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

On Windows, add %USERPROFILE%\go\bin to your PATH via System Settings.

Option C - From source

git clone https://github.com/gowtham-sai-yadav/claude-teleport
cd claude-teleport
go build -o claude-teleport .

Check it works: claude-teleport version

Quick start (5 minutes)

You'll run two commands total - one on each computer.

On the OLD computer

1. Open a terminal and run:
   copy

   claude-teleport export
   

2. It prints the name of a file it created, e.g. claude-teleport-backup-20260628-120000.tgz.
3. Copy that one file to the new computer - AirDrop, a USB stick, scp, Google Drive, whatever is easiest.

On the NEW computer

4. Install Claude Code and sign in once (so it sets up your account), then close it.
5. Preview what will happen - this writes nothing:
   copy

   claude-teleport import claude-teleport-backup-20260628-120000.tgz --dry-run
   

   You'll see a table of every project and where it will move to. claude-teleport guesses the new location from your current home folder. If a guess is wrong, fix it with --map:
   copy

   claude-teleport import bundle.tgz --map /home/oldname=/Users/newname --dry-run
   

6. Happy with the preview? Run it for real:
   copy

   claude-teleport import claude-teleport-backup-20260628-120000.tgz
   

   It asks for confirmation, copies everything into place, fixes the paths, and finishes with a check that your sessions are resume-ready.
7. Put your actual project folders where the table said they'd go (e.g. clone your repos into ~/Desktop/...). Then open one and resume:
   copy

   cd ~/Desktop/my-project
   claude --resume
   

That's it. Your old conversations are there.

One thing that does not transfer: your login. That's on purpose - credentials are locked to each machine and should never travel in a file. Just sign in to Claude Code once on the new computer.

Prefer clicking? Use the GUI

Not a terminal person? Run:

claude-teleport gui

Your browser opens a small wizard where you pick the bundle file, confirm where each project should go, tick the projects you want, and click Import. It shows a live result and the same resume-ready check at the end. Everything runs locally on your own machine - nothing is uploaded anywhere.

Moving between different operating systems

Import runs on the destination machine, so it detects the right OS automatically and translates everything for you, including Windows drive letters and backslashes:

Paths stored inside the transcripts are rewritten in the correct style too. Because transcripts are JSON, Windows paths are matched and re-written in their escaped form (C:\\Users\\you), so nothing is missed.

Command reference

claude-teleport export  [--out FILE] [--config-dir DIR]
claude-teleport import  <bundle> [flags]
claude-teleport inspect <bundle>
claude-teleport verify  [--config-dir DIR]
claude-teleport gui     [bundle] [--port N]

import flags

• inspect prints what's inside a bundle without importing.
• verify checks that the sessions already on this machine are resume-ready.

What gets moved (and what doesn't)

Moved: session transcripts, per-session sidecars, project memory, your user settings.json, prompt history, plan files, plugin manifests, and the portable parts of ~/.claude.json (re-keyed to the new paths).

Never moved - your login. Credentials are machine-locked (macOS Keychain, Windows user profile) and are deliberately left out. Sign in once after importing.

Skipped as junk: caches, telemetry, shell snapshots, lock files, and device-identity fields - all of which rebuild themselves on first run.

Is it safe?

• It never overwrites an existing file by default - it merges and tells you what it skipped. --overwrite makes a timestamped backup of each file it replaces.
• --dry-run shows exactly what will happen before anything is written.
• The riskiest step - rewriting paths inside message text - is off by default. The safe default only fixes the structural cwd field needed to resume. --deep opts into a full rewrite.
• It runs entirely offline. Your bundle and history never leave your computers.

How it works

A bundle is a .tgz archive with a manifest.json written first. The manifest records each project's true absolute path - the piece the lossy folder name throws away - read from ~/.claude.json and from the cwd stored inside each transcript. On import, claude-teleport:

1. works out a new path for each project (auto-detected, or via --map),
2. re-encodes the folder names for the target machine and OS,
3. rewrites the old paths inside transcripts (JSON-escaped, so Windows paths match),
4. merges everything in without overwriting, and
5. verifies each migrated project's cwd matches its new folder.

FAQ

Will this delete anything on my old machine? No. export only reads.

Do I need Claude Code installed first on the new machine? Yes - install it and sign in once so your account is set up, then import.

My new username/OS is different. That's the whole point - it's handled. Preview with --dry-run and adjust with --map if a guess is off.

I only want a couple of projects. Use --project <path-or-folder> (repeatable), or tick just those in the GUI.

Where is all this stored? Under ~/.claude/ and ~/.claude.json (or %USERPROFILE% on Windows). Set CLAUDE_CONFIG_DIR to relocate it; claude-teleport respects that variable.

Contributing

Issues and pull requests are welcome. To develop:

go test ./...     # run the tests
go vet ./...      # static checks
gofmt -l .        # should print nothing
go run . gui      # try the wizard locally

CI runs lint and tests on Linux, macOS, and Windows. Tagging vX.Y.Z builds and publishes release binaries automatically.

Star history

License

MIT © Gowtham Sai Yadav