tmux-sync

README

tmux-sync

Port a live remote tmux session — layout, scrollback, every running nvim's open files & splits, the claude conversation, and the working files — to a container on your laptop, work offline, then check it back in and resume on the remote.

Status: alpha — CLI is a skeleton. See SPEC.md for the design. The working bash prototype that informed it lives in reference/tmux-sync.sh — sourceable directly if you want a usable v0 while the Go binary lands. No tagged releases yet; once tagged, binaries appear on the releases page.

Why

You're driving a claude-pod over the network and you need to go offline (a plane, a train, dead wifi) without losing your session. tmux-sync checkout captures the whole frame and pulls it down; you keep working; tmux-sync checkin pushes it back and you resume on the remote.

Install

Pre-built binaries are published with each release for darwin/{arm64,amd64} and linux/{amd64,arm64}. Pick the tarball from the releases page, extract, and drop tmux-sync somewhere on your PATH.

The same binary is installed into the claude-pod container image so the remote half is always the matching version.

Auto-update. Once installed, tmux-sync checks GitHub Releases at most once every 6 hours and atomically replaces itself in place when a newer tag is published; the new version takes effect on the next invocation. Opt out with TMUX_SYNC_NO_UPDATE=1. Inside the pod the binary is root-owned, so auto-update is naturally a no-op there — version-pinned by the image as intended.

Usage

tmux-sync checkout --from homelab
# ...work offline...
tmux-sync checkin  --to   homelab

Endpoints (k8s pod, GCP VM container, the laptop) live in ~/.config/tmux-sync/config.yaml. See SPEC.md.

Design — short version

• Reconstruct, don't migrate — capture state, relaunch processes (no CRIU).
• Disk is the source of truth — every nvim is :wall'd + :mksession'd before snapshot, so nothing important lives only in memory.
• Backend-agnostic — one Exec primitive; k8s, GCP VM, and the laptop are all just endpoints behind a Driver.
• Full session restore is required, not optional — tmux-resurrect for layout + scrollback + which command was running, mksession for nvim interior, claude --resume for the conversation.

Full details in SPEC.md.

License

MIT.

Documentation

Overview

Command tmux-sync ports a live remote tmux session to your laptop and back.

It captures the full remote session — tmux layout, scrollback, every running nvim's open files/splits, claude's conversation transcript, and the working files — moves it to a container on your laptop, lets you work offline, and reconciles the changes back when you return.

See SPEC.md in this repo for the design.