Sessions

A session is a long-lived, interactive conversation with an agent — it keeps context across many turns and can use tools the whole time, unlike a one-shot rupu run.

What is a session

rupu run is a single shot: you give an agent one prompt, it works, and it exits. A session is the conversational counterpart. You start it once against an agent, then keep sending follow-up prompts; each turn sees the full history of everything that came before — earlier messages, tool calls, file edits, and results.

Because the context survives between turns, a session is the right surface for back-and-forth work: ask a question, read the reply, refine, correct course, ask the agent to also look at the writer side. The same agent files in .rupu/agents/ that power rupu run back a session — a session just wraps one in a durable, multi-turn loop.

Starting & using a session

Everything lives under the rupu session subcommand. The full set:

start accepts an agent name, an optional target reference (e.g. github:owner/repo#42), and an optional opening prompt. Useful flags: --prompt (pass the opening message without it being parsed as a target), --mode ask|bypass|readonly to set the permission mode, --into <PATH> to choose a clone directory for repo targets, --no-stream to disable token streaming, and --detach to start the first turn without auto-attaching to the live view.

# start a session against an agent, with an opening question
$ rupu session start code-explorer --prompt "where is the run target parsed?"

# …rupu prints the new session id, e.g. 01JABCD…  then continue the thread:
$ rupu session send 01JABCD… "now also check the writer side"

# re-open the live view of a running session, or list what you have
$ rupu session attach 01JABCD…
$ rupu session list

Interactive features

Inside the live view (after start or attach) the session screen is built for keyboard-driven, conversational use.

Slash commands & Tab completion

Slash commands are the control surface of a live session — /help, /status, /history, /transcript, /runs, /cancel, /compact, /stop, /detach, and /quit, plus routed roots that reach the rest of the CLI (/workflow, /session, /issues). Press Tab on a / buffer to open an in-screen popup of matching commands with the first highlighted; Tab / Down / Up navigate (and wrap), Enter accepts the highlighted command into the buffer (without submitting — routed roots get a trailing space so you can type the subcommand), and Esc dismisses. Typing re-filters the list live by strict prefix. This turns the slash catalog from something you have to memorize into something you can discover and complete.

Role blocks

Each turn renders as a visually distinct block so it's easy to see where one turn ends and the next begins as the transcript scrolls. The agent's turn leads with a status glyph and a labelled header (● agent · gpt-5 · ⇡ 2,311 ⇣ 246), and its body lines carry a colored left rail (│) that reads continuously into the nested tool-call tree below it. Your turns render as ▸ you with a brand-tinted rail. The glyph shifts while a reply streams (◐) versus when it's complete (●), giving the conversation a clear, consistent visual grammar.

The session worker

A session is backed by a persistent worker process that runs in the background and survives between turns. That's what lets rupu session send continue the same conversation with all its context intact rather than starting over — each prompt is handed to the already-running worker for the next turn. The live view is just a window onto that worker: --detach (or the /detach command) leaves the view while the worker keeps running, and rupu session attach re-opens the view on the current or last run. rupu session stop shuts the worker down.

Sessions in the control plane

The web control plane can drive a live session as a chat: you send a prompt, a turn starts, and the transcript streams back token-by-token with a "working…" indicator while it's in flight, per-turn errors surfaced inline, and final status, tokens, and any failure shown the moment the turn ends. This is the same session surface as the CLI — the same on-disk sessions, transcripts, and worker — just presented as a turn-by-turn chat in the browser instead of the terminal.

Sessions vs runs vs workflows