developer/session-tools
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
session-tools/README.md

2.5 KiB
Raw Blame History

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:

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/:

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