Metadata-Version: 2.5
Name: commuter
Version: 0.2.0
Summary: Portable AI coding session transfer between machines (Claude Code push/pull)
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

# 🚂 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:

```bash
$ 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:

```bash
uv tool install --from . commuter
```

---


![commuter demo](commuter.gif)


## Why?

Claude Code's [Remote Control](https://code.claude.com/docs/en/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:**

```bash
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:**

```bash
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:**

```bash
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):

```bash
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:
```bash
cd ~/github/commuter
uv tool upgrade --from . commuter   # installs/upgrades from local source
commuter --help
```

### Path mapping (if your machines have different paths)

```bash
# 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](https://pipx.pypa.io/) (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

| Command | Description |
|---------|-------------|
| `commuter list` | Show all Claude Code sessions on this machine |
| `commuter export <id> -o file.json` | Export a session to a portable bundle |
| `commuter export --latest -o file.json` | Export the most recent session |
| `commuter export --from-cwd -o file.json` | Export the session for the current directory |
| `commuter import file.json` | Import a session and launch Claude Code |
| `commuter config set path-map "A" "B"` | Set up path translation between machines |
| `commuter push` | Export current directory's session to transfer dir |
| `commuter pull` | Import all pending sessions from transfer dir |
| `commuter to HOSTNAME` | Send current directory's session directly to a host over SSH |
| `commuter from HOSTNAME` | Pull the current project's session from a host over SSH |

### Import flags

| Flag | Description |
|------|-------------|
| `--project-dir PATH` | Override auto-detected project directory |
| `--replace` | Force-replace existing session without prompting |
| `--no-launch` | Import without launching Claude Code |
| `--dry-run` | Preview what would happen |

### Push / pull shortcut

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

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

Then, from each project you want to transfer:

```bash
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:

```bash
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*:

```bash
# 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:

```bash
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](https://code.claude.com). Jokes by Claude

## License

MIT
