Sessions that survive: attach, detach, and never lose an agent mid-task

Close the laptop mid-refactor. Reattach tomorrow: same tabs, same panes, same agent conversations. How rysh sessions persist everything that matters.

The oldest promise of a terminal multiplexer: your SSH connection dies, your work doesn't.

The agent era raises the stakes. It's not six shells you'd lose anymore — it's six conversations: an agent halfway through a refactor, a test loop with an hour of context, an approval you haven't answered yet. Losing a shell costs you a command. Losing an agent costs you everything it knew.

So rysh treats sessions as first-class infrastructure, not a convenience.

The lifecycle

rysh                       # start (or resume) the default session
rysh myproject             # start a named session
rysh detach myproject      # gracefully detach a running session
rysh attach myproject      # reattach — everything as you left it
rysh list-sessions         # what exists, and in what state
rysh delete-session old    # tear one down completely

From inside the TUI, Ctrl+O d detaches (tmux-style prefix; any other key cancels — Ctrl+P d works too). From outside, rysh detach signals the running process to unhook cleanly.

Every session lives in a local registry on disk (~/.local/state/rysh/sessions/): name, working directory, state, PID, last update. Three states matter:

• running — a TUI is attached
• detached — the session lives on headless; agents keep their state, and you can still talk to it with rysh send
• stopped — exited; its persisted state waits for the next start

delete-session is honest about cleanup: it removes the record, terminates the process if it's still alive, and deletes the session's data directory. No ghost daemons.

What actually survives

Here's where rysh differs from "tmux but AI." Each session runs its own embedded NATS server with JetStream enabled — a tiny persistent message bus, in-process, storing data per session under ~/.local/state/rysh/nats/{session}/. Two KV buckets carry the state:

• rysh-workspace — the structure: tabs, lanes, pane groups, stack order, flex weights, active indices. Persisted on every structural change.
• rysh-panes — one entry per pane (keyed by its UUID): output buffer, status, input mode, last command.

So what comes back on rysh attach isn't a screen-shaped approximation. It's:

• your tab and lane layout, exactly
• every pane's scrollback and history
• every pane's input mode — the pane you left in prompt mode wakes up in prompt mode
• stack order in every deck — the card you left on top is still on top

Pane writes are time-gated (at most one KV write per couple of seconds per pane) so a chatty build log doesn't turn persistence into a write storm. Workspace structure, being rarer and more precious, persists immediately.

On startup, the workspace actor attempts a restore from KV first; only if there's nothing to restore does it bootstrap fresh tabs. Recovery is the default path, not the exception.

The ##session commands

You don't have to leave the input line to manage sessions. The ## command language covers it:

##session            # info about the current session
##session list       # all known sessions, current marked with >
##session switch qa  # ensure qa's daemon is running (spawn if stopped)
##session reload     # flush workspace state to KV, refresh the record

The detail that matters: these operate daemon-side through the session registry. The TUI is just a client. That's why the same commands behave identically in the CLI and the desktop app — and why a session isn't "a window you keep open" but a service you connect to.

The workflow this unlocks

The lid-close test. Mid-refactor, an agent grinding through a rename across forty files. Laptop dies, meeting starts, whatever. rysh attach an hour later: the pane's transcript, the agent's status, your place in the approval queue — intact. You answer the pending diff approval and keep moving.

The remote poke. Session detached on your desk machine, you're on a different box. rysh send myproject "status?" --mode prompt drops a prompt into the active pane without attaching a TUI at all. Attach later to read the details. (That command is good enough to get its own article.)

The per-project brain. One session per project, permanently. rysh clientwork in the morning is not "open my tools" — it's resume the working state of that project: the ops pane, the worker stack, the agent that already knows what you did last week. Session-per-project turns setup time into attach time.

Honest edges

What survives is state, not processes-in-amber: a shell command that was mid-flight when the machine rebooted is not resurrected mid-flight — you get its output up to the moment, and your agents' conversational state comes back from KV. And all of this is local-first and self-hostable: the registry, the NATS data, the buffers — files on your disk, talking to Claude with your API key. There's no cloud copy of your session unless you explicitly share a pane upstream.

A multiplexer keeps your shells alive. Rysh keeps your working memory alive. Once agents hold real context, that's not a nice-to-have — it's the difference between a tool and a colleague who remembers.

Rysh is early. We're recruiting design partners — teams who'll run real work in persistent agent sessions and tell us where it hurts. → rysh.ai/design-partner

Related: rysh send: drive your agents from any shell · Persistent by default: JetStream KV