[luv-35] Run workspaces in tmux on a remote machine over SSH (#35)

Point luv at another machine and every workspace command runs there
inside a tmux session that survives disconnects. `luv ls` shows what is
running across hosts and `luv continue` reattaches.

Local luv becomes a thin dispatcher: it re-invokes luv itself on the
remote over SSH, so every existing flag works there unchanged. tmux
wraps the whole remote invocation rather than just the agent, so the
clone and any docker compose start-up are inside the pane from second
zero, a dropped connection never loses work, and the existing
stop_docker teardown stays bound to the agent exiting instead of the
SSH client going away. The three os.execv sites are untouched.

The laptop cannot know the workspace number ahead of time -- it comes
from gh api on the remote -- so the dispatcher records a random token
and the remote stamps it onto the session as an @luv_id tmux option.
The registry in ~/.luv/sessions.json joins on that token, so renaming
the placeholder session breaks nothing. Reconciliation keeps entries
for hosts that did not answer rather than pruning them, distinguishing
the cases by ssh's 255 exit code: running `luv ls` offline must not
wipe the session list.

New commands: luv config (wizard plus set/get/list/unset), luv ls,
luv continue. New flags: -s HOST, -i PATH, --local. -nit and --clean
skip tmux so stream-json still pipes to a local consumer. --clean now
refuses to delete a workspace with a live tmux session unless forced.

Docs cover architecture, preparing a fresh Ubuntu box including SSH key
setup, the full config reference, the registry internals, and
troubleshooting for each concrete failure mode.


Claude-Session: https://claude.ai/code/session_01Sw5G6a6KX2rsEPLAy4V6jt

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: NiveditJain

README.md

@@ -2,7 +2,7 @@
 
 A CLI that launches Claude Code or Codex agents on GitHub repos with isolated workspaces and optional Docker dev environments.
 
-`luv` clones a repo, creates a branch, and drops you into a Claude session ready to work. When the repo ships a `.luv/settings.json`, it spins up Docker Compose automatically so every command runs in the right environment.
+`luv` clones a repo, creates a branch, and drops you into a Claude session ready to work. When the repo ships a `.luv/settings.json`, it spins up Docker Compose automatically so every command runs in the right environment. Point it at a remote machine and the whole thing runs there in a tmux session you can detach from and reattach to later.
 
 ## Install
 
@@ -19,8 +19,8 @@ pip install luv-cli
 ## Quick start
 
 ```bash
-# Configure your default GitHub org (one-time setup)
-luv --init
+# One-time setup: default GitHub org, and optionally a remote machine
+luv config
 
 # Create a new workspace and launch Claude
 luv my-repo "add user authentication"
@@ -51,6 +51,10 @@ luv -r my-repo 42
 
 # Clean up fully-merged workspaces
 luv --clean
+
+# See what's running on your remote machine, and reattach
+luv ls
+luv continue
 ```
 
 ## How it works
@@ -62,11 +66,18 @@ luv --clean
 
 All workspaces live under `~/prs/`. The number comes from the repo's GitHub issue counter to avoid collisions.
 
+With a remote host configured, steps 1–4 happen on that machine inside a tmux session instead — see [Remote sessions](#remote-sessions).
+
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `luv --init` | Configure default GitHub org |
+| `luv config` | Interactive setup: remote host, SSH key, default org |
+| `luv config set\|get\|unset <key> [value]` | Read or write a single setting |
+| `luv config list` | Show all settings |
+| `luv --init` | Configure default GitHub org only |
+| `luv ls [--host H] [--prune]` | List live sessions across hosts |
+| `luv continue [<repo> [number]]` | Attach to a live session |
 | `luv [org/]<repo> [prompt...]` | Create a new workspace and launch Claude (default) |
 | `luv --codex [org/]<repo> [prompt...]` | Create a workspace and launch Codex in YOLO mode |
 | `luv [org/]<repo> -b <branch> [prompt...]` | Create a workspace based off `<branch>` instead of the default |
@@ -90,6 +101,9 @@ All workspaces live under `~/prs/`. The number comes from the repo's GitHub issu
 | `-m MODEL` | Model to use; Claude defaults to `claude-opus-5`, while Codex uses its configured CLI default |
 | `-b BRANCH` | Base a new workspace off `BRANCH` (clone + branch from it); recorded in `git config luv.base` so the PR can target it |
 | `-e` | Env: pass `LUV_*` environment variables (with prefix stripped) into the session |
+| `-s HOST` | Run on `HOST` over SSH, overriding the configured remote host |
+| `-i PATH` | SSH identity file to use for this invocation |
+| `--local` | Force local execution even when a remote host is configured |
 | `-f`, `--force` | Skip safety checks (with `--clean`) |
 | `--safe` | With `--clean -f`, only delete workspaces older than 24h (mtime) |
 
@@ -143,6 +157,24 @@ The `dev-environment` service **must** have the selected agent CLI (`claude` or
 
 Docker mode works with all flags: `-n` opens a bash shell in the container, `-r` resumes a Claude session in the container.
 
+## Remote sessions
+
+Point `luv` at another machine and every workspace command runs there, inside a tmux session that survives disconnects.
+
+```bash
+luv config                          # set the remote host, SSH key, and org
+luv myrepo "fix the flaky test"     # clones and launches Claude on the remote
+                                    # ...close the laptop, go home...
+luv ls                              # see what's still running
+luv continue                        # reattach exactly where you left off
+```
+
+`luv` re-invokes itself on the remote over SSH, so every flag works there unchanged. The remote needs `luv`, `tmux`, `gh`, and `git` on its `PATH`.
+
+Use `--local` for a one-off local run, `-s HOST` to target a different machine, and `-i PATH` for a different SSH key.
+
+Full guide, including how to prepare a fresh Ubuntu box and set up SSH keys: **[docs/remote-sessions.md](docs/remote-sessions.md)**.
+
 ## Workspace cleanup
 
 `luv --clean` scans `~/prs/` and safely removes workspaces that are fully pushed. It checks:
@@ -153,12 +185,28 @@ Docker mode works with all flags: `-n` opens a bash shell in the container, `-r`
 
 Use `luv --clean -f` to skip all safety checks and delete everything. Add `--safe` (i.e. `luv --clean --safe -f`) to restrict force-delete to workspaces whose folder mtime is older than 24 hours, leaving recently-touched workspaces alone.
 
+Workspaces with a live tmux session are skipped unless you pass `-f`.
+
 ## Configuration
 
-Run `luv --init` to set your default GitHub org. This saves to `~/.luv/config.json`.
+Run `luv config` for interactive setup, or `luv --init` to set just your default GitHub org. Both save to `~/.luv/config.json`:
+
+```json
+{
+  "org": "exosphere",
+  "prs_dir": "~/prs",
+  "remote": {
+    "host": "box",
+    "identity_file": "~/.ssh/id_ed25519",
+    "dir": "~/prs"
+  }
+}
+```
 
 You can also pass `org/repo` inline to override the default for any command (e.g., `luv other-org/my-repo`).
 
+Every key, with defaults and resolution order: **[docs/configuration.md](docs/configuration.md)**. The session registry that backs `luv ls`: **[docs/sessions.md](docs/sessions.md)**.
+
 ## License
 
 MIT

docs/configuration.md

@@ -0,0 +1,140 @@
+# Configuration
+
+luv reads a single JSON file: `~/.luv/config.json`. It is created by
+`luv config` and can be edited by hand.
+
+- [The `luv config` command](#the-luv-config-command)
+- [Keys](#keys)
+- [Resolution order](#resolution-order)
+- [Multi-host example](#multi-host-example)
+- [Not this file](#not-this-file)
+
+## The `luv config` command
+
+```bash
+luv config                       # interactive wizard
+luv config list                  # show everything, as dotted keys
+luv config get remote.host
+luv config set remote.host box
+luv config unset remote.host     # back to local-only
+```
+
+`set` parses the value as JSON when it can, so numbers, booleans, and lists work
+as you'd expect:
+
+```bash
+luv config set remote.port 2222                    # → 2222 (number)
+luv config set remote.ssh_opts '["-o","Compression=yes"]'
+luv config set org exosphere                       # → "exosphere" (string)
+```
+
+Anything that isn't valid JSON is stored as a plain string, which is what you
+want for hosts, paths, and org names.
+
+`luv --init` still exists and sets only the org.
+
+## Keys
+
+### `org`
+
+*string.* Default GitHub owner, used when you write `luv myrepo` instead of
+`luv someorg/myrepo`. Set by `luv --init` or the wizard.
+
+The **laptop** resolves this before dispatching, so a remote machine never needs
+its own `org` configured.
+
+### `prs_dir`
+
+*string, default `~/prs`.* Where workspace folders are created on **this**
+machine. `~` is expanded.
+
+### `remote.host`
+
+*string.* SSH destination — an `~/.ssh/config` alias (`box`), a `user@host`, or
+a bare hostname. **Setting this turns on remote mode**: every workspace command
+then runs there. Unset it, or pass `--local`, to run locally.
+
+### `remote.identity_file`
+
+*string.* Path to the SSH private key, passed as `ssh -i`. `~` is expanded by
+luv, since `ssh` won't expand it when luv execs directly rather than through a
+shell.
+
+### `remote.port`
+
+*number.* Passed as `ssh -p`. Omit for the default 22.
+
+### `remote.dir`
+
+*string.* Workspace root **on the remote**. Forwarded to the remote luv, which
+uses it in place of its own `prs_dir`.
+
+### `remote.luv_bin`
+
+*string.* Full path to `luv` on the remote. Only needed when a login shell
+there can't find it on `PATH` — see the
+[troubleshooting section](remote-sessions.md#troubleshooting).
+
+### `remote.ssh_opts`
+
+*list of strings.* Extra arguments inserted into every `ssh` invocation, e.g.
+`["-o", "ServerAliveInterval=30"]`. Prefer `~/.ssh/config` for anything durable.
+
+### `remote.hosts.<name>`
+
+*object.* Per-host overrides. Any of `identity_file`, `port`, `dir`, `luv_bin`,
+or `ssh_opts` may be set here and takes precedence over the `remote.*` value of
+the same name. This is what makes `-s otherbox` usable: without it, one global
+key would be wrong for every host but the default.
+
+## Resolution order
+
+**Host:** `-s HOST` → `remote.host`. If neither, luv runs locally.
+
+**Per-host settings:** `-i PATH` (identity only) → `remote.hosts.<host>.<key>` →
+`remote.<key>`.
+
+**Workspace root:** `_LUV_PRS_DIR` (set by the dispatcher from `remote.dir`) →
+`prs_dir` → `~/prs`.
+
+**Org:** `org/repo` written explicitly → `org` from config → error.
+
+`--local` overrides everything and is rejected alongside `-s` or `-i`, since
+those combinations contradict each other.
+
+## Multi-host example
+
+```json
+{
+  "org": "exosphere",
+  "prs_dir": "~/prs",
+  "remote": {
+    "host": "box",
+    "identity_file": "~/.ssh/id_ed25519",
+    "dir": "~/prs",
+    "ssh_opts": ["-o", "ServerAliveInterval=30"],
+    "hosts": {
+      "gpu-box": {
+        "identity_file": "~/.ssh/gpu_key",
+        "port": 2222,
+        "dir": "/scratch/prs",
+        "luv_bin": "/opt/venv/bin/luv"
+      }
+    }
+  }
+}
+```
+
+With this, `luv myrepo "…"` goes to `box` on port 22 with `id_ed25519`, and
+`luv -s gpu-box ml "…"` goes to `gpu-box` on port 2222 with `gpu_key`, cloning
+into `/scratch/prs` and using an explicit luv binary.
+
+## Not this file
+
+Two other files are sometimes confused with this one:
+
+- **`~/.luv/sessions.json`** — the session registry, written by luv itself. Not
+  configuration; see [sessions.md](sessions.md).
+- **`<repo>/.luv/settings.json`** — a *repo-local* file, committed to the repo,
+  whose only key is `compose_file`. It turns on Docker mode for that repo and
+  has nothing to do with `~/.luv/config.json`.