Skip to content

tmux & live sessions

With tmux ≥ 3.2 installed, kora chat can run inside a private tmux session so the TUI process survives terminal closes, SSH drops and accidental quits. tmux is optional — everything works without it.

Terminal window
kora chat --tmux=on # require tmux — error if missing
kora chat --tmux=auto # use tmux when available (recommended)
kora chat --no-tmux # force the direct path

Inside the TUI everything is identical. Ctrl+B then d detaches — the process keeps running, including mid-turn.

Two details worth knowing:

  • The tmux status bar is disabled — new-session/attach-session chain set-option -g status off on the private socket, so the TUI owns the whole screen.
  • Session names are readable — a wrap starts as kora-draft-<hex> while no session id exists; once the id materializes the inner TUI renames it to kora-<session-id>, and attach.json is republished with the new name.

KORA_TMUX=on|auto|off sets the default mode when no flag is passed; flags always win. A kora process already inside the profile’s own socket never nests a second wrap.

Terminal window
kora chat -r # the resume flow reattaches the live process
kora chat -r <name-or-id> --tmux=on

Each profile gets its own tmux server on a private socket (-L kora, -L kora-dev), so kora’s sessions never appear in your regular tmux ls. Custom KORA_PROFILE_ROOT directories get a hashed socket name (kora-<hash>).

Reattaching an older wrap with the same binary keeps its recorded name — drafts created before the rename behavior keep kora-draft-* until killed and restarted.

Any session with a live attachment — a --tmux TUI or a kora attach client — publishes <profile>/sessions/<id>.attach.json. Everywhere sessions are listed you see it:

  • kora sessions → ● live in the row
  • kora sessions --json → "live": true
  • /sessions and the # picker inside the TUI → ● marker

The marker reflects a checked live process (PID + socket), not just the file — a crashed process stops showing ● even if the file lingers.

/quit inside the TUI kills its tmux session and removes the marker. If a session leaks:

Terminal window
tmux -L kora ls # see what's on the socket
tmux -L kora kill-session -t <name> # one session
tmux -L kora kill-server # or -L kora-dev on the dev profile — everything
kora sessions # ● is gone

The fullscreen settings overlay (/settings, then the Live tab, or /help) lists every live kora host on the profile: attach records verified against real liveness, tmux sessions on the profile socket with no record, and the current session’s in-process subagents.

  • ↑/↓ move the cursor, x kills the row: chat wraps and tmux orphans die on the dedicated socket, serve attachments go through the wire kill op (the control plane cancels the turn and drops clients), stale records are cleared on the spot. Subagent rows are killed in-process — x aborts that one child (status failed, terminal reason user_abort) without stopping the parent turn or its siblings; terminal children report “nothing to kill”.
  • r refreshes; the row for the TUI’s own wrap is guarded against kill — detach with ctrl+b d instead.
  • Wrapped sessions get a readable name (kora-<session-id>) once the session id materializes, so tmux -L <socket> ls shows who owns each process. The tmux status bar is disabled — the TUI owns the whole screen.
  • --tmux=on errors immediately → tmux missing or older than 3.2; install it or use --tmux=auto.
  • No ● on a wrapped session → the marker appears only while a live attach exists; verify with kora sessions --json that the process is still alive.
  • Reattach starts a fresh TUI instead of joining → the tmux session died (reboot, kill-server); the chat history is intact — the wrap is process liveness, not session data.
  • Leftover kora-* sessions in tmux -L kora ls → kill them or the whole server; session files under <profile>/sessions/ are unaffected.
  • Windows → not supported; the wrap is a Unix-only path and --tmux is a no-op elsewhere.