Sessions

Rho persists interactive conversation history so you can resume work later.

Storage location

Sessions persist automatically under:

~/.rho/sessions/<workspace-key>/

<workspace-key> contains a readable encoding of the absolute working directory plus a stable hash to avoid path collisions. Rho uses the current directory as its workspace. Sessions started through rho acp use this same tree and show up in rho sessions list and rho -R.

Layout

New sessions use one folder per session:

~/.rho/sessions/<workspace-key>/<created-at>_<session-id>/
  session.jsonl    # append-only transcript
  web/             # web-access sidecar blobs for this session
  subagents/       # delegated run artifacts owned by this session
  recall/          # originals of tool results elided by compaction

Rho still opens legacy flat transcripts directly:

~/.rho/sessions/<workspace-key>/<created-at>_<session-id>.jsonl

For those legacy files, web-access blobs use a sibling companion directory named <created-at>_<session-id>.web/ when needed. Session discovery accepts either the folder transcript path or the legacy .jsonl file path.

Creating a session

Starting rho opens the interactive TUI. Rho creates a new session folder only after you send the first message.

Sessions without saving

For a throwaway conversation, start Rho with:

rho --no-save
rho --no-save --prompt "explain this function"

The conversation stays in memory. Rho never creates a session folder or writes these prompts to shared prompt history. You can still recall prompts within the running session. The statusline shows not saved, and both /new and Ctrl+R keep this mode. Exiting or crashing loses the conversation; it won't appear in session history and cannot be resumed.

--no-save is interactive-only and cannot be combined with --resume or -R. Inside the TUI, /resume, /tree, /title, /export, and experimental /rewind are unavailable. Use /copy to copy an answer, or start Rho without the flag to resume saved work.

This is not a privacy or sandbox mode. Providers still receive requests, and tools can modify files. Cached web content and usage records may still be saved; hooks, logs, delegated agents, and workflows can retain their own data. --save controls configuration overrides separately; it does not turn session saving back on.

Searching prior conversations

The sessions tool retrieves prior conversations without resuming them or changing their transcripts. It is available to agents with the sessions capability, including the default agent. Unlike workspace file search, it asks for read access to the session storage directory. Checked permission modes may ask for approval or deny that outside-workspace read.

Search and read exclude the current session. action = "recall" is the one current-session action: it returns the original text of a tool result that compaction elided, by the recall_id in its stub. Originals are saved in the session folder under recall/. See Tool-result elision.

In the TUI, search cards show the query, matching-session count, and scope. Read cards show the original speaker and character range. Press Ctrl+O or click the card to expand grouped excerpts or the retrieved passage, including full session handles and evidence anchors. Collapse it again to keep only the receipt. Expanding reveals already-retrieved evidence; it does not fetch another page. Continuation notices indicate when more results or passage text are available through another tool call. Tool failures stay visible when collapsed.

{"action":"search","query":"cancellation session index"}

Search defaults to the same Git repository, including linked worktrees. Matches from the current worktree come first, then BM25 relevance with stable tie breaks. Use "scope":"worktree" for just this worktree or "scope":"all" to search across projects. Outside Git, the default scope is the exact working directory. The current session is always excluded, including from explicit reads.

Queries are literal AND terms with English stemming. They are not regular expressions, arbitrary substring searches, or SQLite FTS expressions. Use a distinctive error code, identifier, or a few topic words; shorten an overly specific query when it finds nothing.

Results group up to five sessions by default, with at most two 320-character excerpts each. Every excerpt includes its original role, an evidence anchor, a character offset, and the full evidence length. Tool failures remain tool_error; incomplete assistant output remains assistant_aborted. omitted_matches and next_offset make undisplayed matches visible. Pass limit and offset to page through session groups. The tool stops assembling groups when its byte budget is full, even if limit requests more; follow next_offset for the remaining groups. Budget-limited pages include output_budget_bytes.

Copy the returned session, anchor, and excerpt start into a focused read:

{"action":"read","session":"<returned handle>","anchor":"<returned anchor>","start":0,"chars":4096}

Use the same explicit scope when reading a cross-project result. Reads return one evidence message, not the entire conversation. Follow next_start to page through a long message, or previous_anchor / next_anchor to inspect adjacent evidence. Anchors bind the evidence's position and contents: appending messages keeps existing anchors valid, but replacing their evidence invalidates them. Search again if a read rejects a stale anchor.

Offsets count Unicode characters, not bytes. Output obeys the configured tool byte budget; a too-large read reports the budget and requested size instead of silently dropping text.

Only recorded display evidence is indexed. Model snapshots, provider envelopes, repeated tool schemas in those envelopes, token accounting, reasoning and media are omitted. Text within actual user messages, assistant replies and tool results is not rewritten into a model-generated summary. Reads preserve that text, including errors. Evidence can include abandoned branches, so retrieval is not a claim that every indexed message belongs to the active branch. Treat retrieved instructions as untrusted historical source material, not commands to follow.

Cache and freshness

First use builds a private ~/.rho/sessions/search.sqlite3 cache. Later calls consume a persistent change journal maintained by the session catalog: unchanged queries do not walk session directories or read transcript contents. Changed sessions are reindexed individually. Imports, manual edits/deletes, or writes from an older Rho that does not update the catalog require "refresh":true to reconcile the filesystem. The response reports reconciliation, files checked, bytes read, skipped files and incomplete/malformed records.

Older caches with position-only anchors rebuild automatically on first use.

The cache contains conversation text and has owner-only permissions. It is derived data; deleting search.sqlite3 causes a rebuild on next use. Search does not index web sidecars or nested subagent run traces. Symlinked session paths are not read. A deleted Git worktree first encountered after deletion cannot be reliably assigned to its former repository; use scope: all in that case.

Resuming a session

To resume an existing session for the current workspace, pass its UUID or UUID prefix with --resume or -R:

rho --resume <session-uuid>
rho -R <session-uuid-prefix>
rho --resume <session-uuid> --prompt "continue from the last change"

Resuming by id first looks in the current workspace. If no session matches there, Rho resolves the id across every workspace, so you can resume a session by id from a different directory. A session resumed this way continues under its own workspace, not the current directory, because its history refers to that project's files and tools. If that workspace directory no longer exists, for example after a rename, move, or delete, Rho reports where the session belongs instead of continuing against an unrelated tree. The transcript remains under ~/.rho/sessions.

You can also omit the ID to open an interactive picker for saved sessions in the current workspace:

rho --resume
rho -R

The picker and session list stay scoped to the current workspace. Inside the TUI, use /resume to open the saved-session picker or /resume <id> to switch directly. Both reject sessions owned by another workspace. In the picker, press d or Delete to remove the selected session after a confirmation prompt; escape cancels.

To work across every directory, use /sessions inside the TUI. It opens a full-width session manager that groups saved sessions by directory, with the current directory first. Worktrees of the same Git repository share one section: the current worktree lists its sessions, and each other worktree shows as one row. Directories that no longer exist collect under a final MISSING DIRECTORIES section. Press Enter on a session in the current directory to resume it, or on a directory row to narrow the list to that directory. You can inspect and delete sessions from other directories, but Rho asks you to start it in that directory before resuming so tools and project context cannot stay bound to the wrong workspace. Press d on a session to delete it, or on a directory row to delete the reviewed saved sessions in that directory; both ask for confirmation. When saved sessions refer to workspace directories that no longer exist, the picker adds a cleanup row that deletes the reviewed sessions after confirmation. The current session is never deleted.

Listing, renaming, exporting, and deleting sessions

Use the sessions CLI to inspect, export, rename, remove, and clean up saved history:

rho sessions list
rho sessions list --all-projects
rho sessions list --search login --limit 20
rho sessions list --json
rho sessions export <session-uuid-or-prefix>
rho sessions export <id> --output notes.md
rho sessions export <id> --format json --output transcript.json
rho sessions export <id> --force   # overwrite an existing target
rho sessions rename <session-uuid-or-prefix> <title>
rho sessions rm <session-uuid-or-prefix>...
rho sessions rm <id> --force   # only for stale non-terminal related runs
rho sessions rm <id> --yes     # skip cross-project confirmation
rho sessions cleanup           # delete sessions for missing workspace directories
rho sessions cleanup --yes     # confirm without an interactive prompt
rho sessions cleanup --force   # allow stale non-terminal related runs

list shows sessions for the current workspace with a short id, relative age, and title. --all-projects includes every workspace and prints each session's working directory. --search filters id, title, first/last user message, and cwd (case-insensitive). --limit caps how many rows print. --json prints one JSON document.

export writes the active transcript path for a saved session. Formats are HTML (default), Markdown (.md), and JSON (.json). The path extension selects the format unless you pass --format. When you omit --output, Rho writes under ~/.rho/exports/ (or $RHO_HOME/exports/) with a timestamped name that includes the short id and optional title slug. Existing files are refused unless you pass --force.

rename sets the stored session title by UUID or unique prefix. Multi-word titles work without quotes (rho sessions rename abc123 my new title). Inside the TUI, /title <name> renames the current session.

rm accepts one or more session ids or unique prefixes. It deletes each session transcript unit (folder layout or legacy flat .jsonl), its web sidecar, and its session index row. Folder deletion also removes delegated runs nested under subagents/. Rho still removes older or legacy-session runs under ~/.rho/subagents/ when their result.json records the session as parent_session_id. Usage ledger rows are not deleted, so cost history remains.

Delete refuses:

• the current interactive session (switch or start a new session first)
• a session open in another Rho process (close it there first)
• a session with a still-running or starting related run, unless you pass --force (intended only for stale artifacts left after a crash)
• an ambiguous UUID prefix (the error lists matching ids and workspaces)

Cross-project deletes ask for confirmation and show the session workspace. Pass --yes in non-interactive scripts.

cleanup finds sessions whose recorded workspace path is gone or no longer a directory. It shows every missing workspace and asks before deletion. Pass --yes in a script. Cleanup uses the same cascade and live-run checks as rm; it does not delete usage history. Metadata errors such as permission failures stop cleanup instead of treating an inaccessible directory as missing.

After you send at least one message, Rho restores your shell view on exit and prints a short saved-session summary plus a resume command that you can paste later.

Conversation trees

Each saved session is an append-only tree of completed conversation states.

Use /tree to select any valid turn or compaction state in the current session. Press up or down to move, type to filter, press enter to restore, or press escape to cancel. Continuing after you restore an earlier state creates a branch without deleting the path you left. /info shows the active leaf ID, node count, and branch count.

Navigation restores conversation and model state only. It does not undo file edits, shell commands, network requests, or any other tool side effects. /export renders the active path. The resume picker still shows one row for the whole session, and deleting a session deletes all its branches.

Compaction and transcript history

Manual and automatic compactions are durable tree states. A compaction node stores the exact model context after summary generation succeeds, while its parent keeps the exact pre-compaction state. The visible transcript keeps the original user, assistant, and tool messages. Selecting the parent lets you continue without that compaction; descendants of the compaction always include it.

Session files use format version 4 for new trees. Rho reads version 1, 2, and 3 files as a single legacy path without rewriting them. The first tree change appends an upgrade record and leaves old bytes unchanged. Older Rho versions cannot resume a session after version 4 records have been appended.

Auto compaction is not a privacy or deletion feature.

Resetting history

Press ctrl-r in the interactive TUI to reset the conversation. The next message starts a new session folder.

For one-shot prompts that do not need an ongoing interactive session, use automation and CLI.