session-tools/README.md

# session-tools

Resilient remote-execution wrappers for SSH/tmux patterns across the lilith
host fleet (plum, apricot, black, quinn-vps, ...).

The premise: a bare `ssh host cmd` dies the moment the transport hiccups,
killing whatever was running on the remote. These wrappers run commands inside
a detached tmux session on the remote so the work survives the SSH drop.

## Tools

- **`bin/remote-run <host> <cmd...>`** — One-shot command runner. Spawns a
  detached tmux session on `<host>`, streams stdout/stderr back to your
  terminal, propagates the exit code. If the local ssh dies mid-run, the tmux
  session continues; reattach with `ssh <host> tmux ls` then
  `ssh <host> tmux attach -t <session>`.

- **`bin/tssh <host>`** — Interactive shell wrapper. Auto-attaches to (or
  creates) a per-user tmux session on `<host>` named `claude-$(whoami)`.
  Detach with `Ctrl-b d`; transport drops don't kill the shell.

- **`bin/rclaude <host> [dir]`** — Remote, durable Claude Code session.
  Stacks two resilience layers: tmux survives transport drops, and
  `claude --continue` resumes the per-directory session from
  `~/.claude/projects/` after anything kills the host itself. Re-running
  with the same `<host>` + `<dir>` always lands back in the same
  conversation. Defaults to `--dangerously-skip-permissions`; override with
  `RCLAUDE_PERMS=default` (or any other `--permission-mode` value).

## Install

On every host that should have these on `$PATH`:

```sh
git clone http://forge.black.local/lilith/session-tools.git ~/Code/@scripts/session-tools
~/Code/@scripts/session-tools/install.sh
```

Symlinks `bin/remote-run` and `bin/tssh` into `~/bin`. Pulls future updates
via plain `git pull` — symlinks track the repo automatically.

## When to use what

| Scenario                                   | Use                                          |
|--------------------------------------------|----------------------------------------------|
| Interactive shell on a remote              | `tssh <host>`                                |
| One-off command (build, test, query)       | `remote-run <host> "<cmd>"`                  |
| Claude Code session on a remote            | `rclaude <host> [dir]`                       |
| Long-running job (>1h, must survive reboot)| `systemd --user` unit on the remote, not ssh |

## Per-host shims (optional)

If a particular host gets used a lot, drop a one-liner into `~/bin/`:

```sh
# ~/bin/apricot-run
#!/bin/sh
exec remote-run apricot "$@"
```