luv-cli 0.0.25__tar.gz → 0.2.0__tar.gz

{luv_cli-0.0.25 → luv_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: luv-cli
-Version: 0.0.25
+Version: 0.2.0
 Summary: Launch Claude Code or Codex agents on GitHub repos with isolated workspaces and optional Docker dev environments
 Project-URL: Homepage, https://github.com/exospherehost/luv
 Project-URL: Repository, https://github.com/exospherehost/luv
@@ -25,7 +25,7 @@ Description-Content-Type: text/markdown
 
 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
 
@@ -42,8 +42,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"
@@ -74,6 +74,14 @@ luv -r my-repo 42
 
 # Clean up fully-merged workspaces
 luv --clean
+
+# Tear down a finished session: kill its tmux, delete its workspace
+luv rm myrepo-42
+luv rm --merged        # everything whose PR has landed
+
+# See what's running on your remote machine, and reattach
+luv ls
+luv continue
 ```
 
 ## How it works
@@ -85,11 +93,21 @@ 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] [--no-pr]` | List live sessions across hosts, with each one's PR link |
+| `luv continue [<repo> [number]]` | Attach to a live session |
+| `luv rm <session\|workspace>...` | Kill a session and delete its workspace on its host |
+| `luv rm --merged [--host H] [-f]` | Remove every session whose PR is merged |
+| `luv rm --dead [--host H] [-f]` | Remove workspaces with no 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 |
@@ -113,6 +131,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) |
 
@@ -166,6 +187,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:
@@ -176,12 +215,55 @@ 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`.
+
+### Removing a specific session
+
+`luv --clean` is a garbage collector: it decides for itself what is safe to
+delete, and never touches a workspace with a live session. `luv rm` is the
+opposite — you name what goes, and it goes, on whichever host it lives on.
+
+```bash
+luv rm myrepo-42          # kill its tmux session, delete ~/prs/myrepo-42 on its host
+luv rm luv-myrepo-42      # the session name works too
+luv rm --merged           # every session whose PR has been merged
+luv rm --dead             # workspaces left behind by sessions that already exited
+luv rm --dead --host box  # scope either selector to one machine
+```
+
+A named target is taken as intent and removed without further checks —
+including any uncommitted work in it. The `--merged` and `--dead` selectors
+list what they matched and ask first; `-f` skips that prompt.
+
+`--dead` is the counterpart to `luv ls`: reconciliation drops a session from the
+registry as soon as its tmux session exits, but the clone it was working in
+stays on the remote disk. Those orphans are invisible to `luv ls` and are
+usually what is actually filling up the box.
+
+Only folders named `{repo}-{N}` are ever eligible — anything else in the
+workspace root is left alone, and a target that doesn't resolve to one is an
+error rather than an `rm -rf`.
+
 ## 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

{luv_cli-0.0.25 → luv_cli-0.2.0}/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,14 @@ luv -r my-repo 42
 
 # Clean up fully-merged workspaces
 luv --clean
+
+# Tear down a finished session: kill its tmux, delete its workspace
+luv rm myrepo-42
+luv rm --merged        # everything whose PR has landed
+
+# See what's running on your remote machine, and reattach
+luv ls
+luv continue
 ```
 
 ## How it works
@@ -62,11 +70,21 @@ 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] [--no-pr]` | List live sessions across hosts, with each one's PR link |
+| `luv continue [<repo> [number]]` | Attach to a live session |
+| `luv rm <session\|workspace>...` | Kill a session and delete its workspace on its host |
+| `luv rm --merged [--host H] [-f]` | Remove every session whose PR is merged |
+| `luv rm --dead [--host H] [-f]` | Remove workspaces with no 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 +108,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 +164,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 +192,55 @@ 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`.
+
+### Removing a specific session
+
+`luv --clean` is a garbage collector: it decides for itself what is safe to
+delete, and never touches a workspace with a live session. `luv rm` is the
+opposite — you name what goes, and it goes, on whichever host it lives on.
+
+```bash
+luv rm myrepo-42          # kill its tmux session, delete ~/prs/myrepo-42 on its host
+luv rm luv-myrepo-42      # the session name works too
+luv rm --merged           # every session whose PR has been merged
+luv rm --dead             # workspaces left behind by sessions that already exited
+luv rm --dead --host box  # scope either selector to one machine
+```
+
+A named target is taken as intent and removed without further checks —
+including any uncommitted work in it. The `--merged` and `--dead` selectors
+list what they matched and ask first; `-f` skips that prompt.
+
+`--dead` is the counterpart to `luv ls`: reconciliation drops a session from the
+registry as soon as its tmux session exits, but the clone it was working in
+stays on the remote disk. Those orphans are invisible to `luv ls` and are
+usually what is actually filling up the box.
+
+Only folders named `{repo}-{N}` are ever eligible — anything else in the
+workspace root is left alone, and a target that doesn't resolve to one is an
+error rather than an `rm -rf`.
+
 ## 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

luv_cli-0.2.0/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`.