🚂 commuter: push/pull for Claude Code (like git push/pull)

Take your AI coding sessions to work and back. (v0.2.0)

Commuter transfers Claude Code sessions between machines. Start a session on your home desktop, export it, commute, import it on your office laptop — and pick up exactly where you left off. Typical session:

$ claude
...
$ git push origin main
$ commuter push

switch machine

$ git pull origin main
$ commuter pull
$ claude --continue

Just like you get the latest code from remote repo, you get the latest Claude conversation from the other computer

Both machines reachable over SSH? Skip the shared folder entirely and hop directly with commuter to <host> (send) or commuter from <host> (pull) — see Direct SSH below.

No cloud dependency. No VPN. No SSH tunnels. Just a JSON file in your Dropbox. Install with:

uv tool install --from . commuter

Why?

Claude Code's Remote Control lets you view a session from your phone — but the session runs on the original machine. If that machine sleeps, loses Wi-Fi, or you need local file access on a different computer, you're out of luck.

Commuter solves this by migrating the session itself — conversation history, project config, everything — so the AI picks up right where you left off on the new machine.

The daily workflow

Morning at home:

cd ~/projects/my-app
claude
# ... work for an hour ...

# Time to leave
commuter export --latest -o ~/Dropbox/session.json

  ✓ Exported session a1b2c3d (47 messages, 12KB)
  ✓ Git snapshot: branch feature/auth @ a1b2c3d
  ✓ Saved to ~/Dropbox/session.json

Arrive at office:

commuter import ~/Dropbox/session.json

  ✓ Mapped to local path: /Users/you/projects/my-app
  ✓ Git check: feature/auth @ a1b2c3d ✓
  ✓ Restored conversation (47 messages)

  Launching Claude Code with restored session...

Claude remembers everything. You continue:

You: Let's continue with the auth module. Where were we?
Claude: We were adding OAuth2 support to the login endpoint...

End of day — back home:

commuter export --latest -o ~/Dropbox/session.json
# commute home...
commuter import ~/Dropbox/session.json

  ✓ Session continuity detected: 47 → 112 messages
  ✓ Replacing local session with imported version
  Launching Claude Code with restored session...

Round-trips are seamless. Commuter detects that the imported session is a continuation of the local one and replaces it automatically — no prompts, no flags.

Setup

Install / Development Workflow

Your preferred release habit (cleaned up):

cd ~/github/commuter
uv build          # creates fresh dist/ with v0.2.0
uv publish
pipx install --force commuter

Note: rm dist/* is no longer needed — uv build overwrites cleanly.
Your habit of working in ~/Dropbox/ai/commuter (while the repo lives at ~/github/commuter) is fully supported — no hard-coded paths remain.

For quick local testing without publishing:

cd ~/github/commuter
uv tool upgrade --from . commuter   # installs/upgrades from local source
commuter --help

Path mapping (if your machines have different paths)

# Tell commuter how paths map between your machines
commuter config set path-map "/home/you/projects" "/Users/you/projects"

If both machines use the same paths, skip this step.

Prerequisites

• Python 3.10+
• pipx (recommended) or pip
• Claude Code installed on both machines
• For push / pull: a shared filesystem between machines (Git, Dropbox, Syncthing, Google Drive, USB stick — anything that moves a file from A to B)
• For to / from: passwordless SSH between the machines, with commuter installed on both (0.2.0+ on both for from)

Commands

Import flags

Push / pull shortcut

For an even faster workflow, configure a shared transfer directory once:

commuter config set transfer-dir ~/Dropbox/.commuter/

Then, from each project you want to transfer:

cd ~/projects/my-app  &&  commuter push
cd ~/projects/other   &&  commuter push

push exports the session for the current directory. Run it once per project you're taking with you.

On the other machine, a single pull picks up everything:

commuter pull

  ✓ Restored conversation (47 messages)    # my-app
  ✓ Restored conversation (31 messages)    # other

  Imported 2 session(s). To resume:
    cd ~/projects/my-app  && claude --continue
    cd ~/projects/other   && claude --continue

Direct SSH: to and from

If the machines can reach each other over SSH, skip the shared transfer directory and move the session directly. There are two directions — the argument is always the other machine:

# Leaving this machine — SEND the current session to office-laptop
cd ~/projects/my-app
commuter to office-laptop
#   → on office-laptop:  cd ~/projects/my-app && claude --continue

# Arriving at this machine — PULL the session from home-desktop
cd ~/projects/my-app
commuter from home-desktop
#   → here:  claude --continue

• to exports the current directory's session as the same bundle push builds, copies it to the destination with scp, and runs commuter import --replace --no-launch there.
• from is the mirror: it runs commuter export --from-cwd on the remote (so the remote picks the right session for the project), copies the bundle back, and imports it locally.

Both require commuter installed on the other machine and visible to non-interactive SSH. from runs export --from-cwd remotely, so the other machine needs 0.1.12+.

If the project lives at a different path on the other machine, either configure path mapping or pass the remote path explicitly:

commuter to   office-laptop --project-dir /Users/you/projects/my-app
commuter from home-desktop  --project-dir /home/you/projects/my-app

commuter host HOSTNAME still works as a hidden alias for commuter to HOSTNAME.

How it works

Commuter exports a session as a single JSON bundle containing:

• Full conversation history (messages, tool calls, results)
• Project directory path
• Project config (.claude/settings.json, CLAUDE.md, .claude/commands/)
• Git state snapshot (branch, commit, dirty files)
• Environment metadata

On import, it restores the session into Claude Code's local storage, translates paths if needed, validates the git state, and launches Claude Code with the restored conversation.

Project MCP config is not currently transferred. If your workflow depends on .mcp.json or other MCP setup, keep those files in Git/Dropbox or configure them on both hosts.

Session continuity

Commuter tracks session lineage by hashing the first N messages. When you import a session that's a continuation of one already on this machine (same beginning, more messages), it replaces automatically. Divergent sessions prompt for confirmation.

This makes the home → office → home round-trip work without friction.

Architecture

commuter/
└── backends/
    └── claude_code.py    # Claude Code backend
    └── (future: codex, gemini, etc.)

The Claude Code-specific logic is isolated behind a backend interface. Adding support for other AI coding tools (Codex CLI, Gemini CLI) is a matter of writing a new backend — the CLI and bundle format stay the same.

Requirements

Commuter assumes your project files are already synced between machines. It transfers the session (conversation + config), not the codebase. Use Git, Dropbox, Syncthing, or whatever you normally use to keep your code in sync.

FAQ

Does my home machine need to stay on? No. That's the whole point. Unlike Remote Control, commuter migrates the session entirely to the new machine. Your home desktop can sleep, shut down, or catch fire (please don't) — the session continues independently on the target machine.

What if I forget to commit before leaving? Commuter warns you. It snapshots the git state on export and checks it on import. If there are dirty files that aren't present on the target machine, you'll see a warning. The session still imports — you just might need to sync those files.

What if my git branches are different on the two machines? Commuter warns you and asks for confirmation. Claude will have context from the original branch, which might be confusing if you're now on a different one.

Can I use this without Dropbox? Yes. Dropbox is just an example. You can use any method to move the JSON file between machines: a USB drive, scp, email it to yourself, AirDrop, carrier pigeon with a flash drive. Commuter doesn't care how the file gets there.

Does it work with Codex CLI / Gemini CLI / Cursor? Not yet. The architecture supports multiple backends, but only Claude Code is implemented today. PRs welcome.

Contributing

Contributions welcome. The most impactful areas:

• New backends — add support for Codex CLI, Gemini CLI, or other tools
• Bug reports — especially around edge cases in session discovery and import
• Platform testing — tested on Linux ↔ macOS; Windows support is untested

Credits

Conceived and directed by Ljubomir Buturovic. Built with Claude Code. Jokes by Claude

License

MIT