Upgrading to Rho 3
In Rho 3, your sessions keep running after you quit. If you quit the TUI or close your editor while the agent works, the turn finishes in the background. rho --resume <id> picks it up later from any terminal.
This page is for Rho 2 users. The changelog lists every change.
Before you upgrade
- Finish or cancel your running workflows. Rho 3 cannot resume a workflow step that Rho 2 left half-finished.
- Copy any session you want to keep opening in Rho 2. Rho 3 opens Rho 2 sessions, but once Rho 3 saves to a session, Rho 2 can no longer open it.
You don't need to change your config first. Rho 3 backs it up and converts it on first start (Configuration).
Install
Install Rho 3 as Installation describes, then run rho as usual.
Rho 3 runs sessions in a background process, the daemon. Rho starts it for you the first time it needs it. You don't need to set up a service. These commands manage it:
rho daemon status # is it running, and what is it doing
rho daemon stop # stop it; running turns stop and show as interrupted
rho daemon restart # restart it, for example after an update
rho doctor # check your setup, the daemon includedWhat feels different
- Quitting the TUI no longer stops the agent. Rho prints the session id when you quit. Run
rho --resume <id>to see what happened while you were away. - Closing your editor, or one of its
rho acpthreads, leaves the session running. Reopen it from the editor or withrho --resume. /jobsin the TUI lists everything Rho is running, across all your projects. You can answer questions, cancel work, and open sessions from there.- Commands the agent runs use the environment of the terminal or editor you prompted from, so
PATH, mise tools, and exported variables work as they do in your shell. See Environment. - Edits to
config.tomlapply to the next session you open. Open sessions keep most of their settings until you reopen them.
New things you can try:
rho run --detach "<prompt>"starts a run in the background and prints its id.rho attach <id>follows it (Running in the daemon).rho run --worktreegives a session its own git branch and checkout, so parallel sessions in one repository don't overwrite each other (Running in a worktree).rho mcp servelets Claude Code, Codex, or another MCP client start and follow your Rho sessions (MCP server).
What you need to change
Use RHO_HOME instead of --config
All sessions use the config in ~/.rho. To use a different config, set RHO_HOME to another directory. That directory gets its own config, sessions, sign-ins, and daemon.
rho, rho run --detach, rho login, and rho acp now refuse --config. A plain rho run, without --detach, still accepts it.
Editor commands
Remove these flags from the command your editor runs for rho acp, or it won't start: --provider, --model, --config, --auth, --reasoning, --permission-mode, and --save. Pick the model and mode in the editor instead.
Tools now run on the machine where Rho runs. Rho no longer asks the editor to read files, write files, or run commands.
Configuration
The first time Rho 3 starts, it converts your config.toml. Display and keybinding settings move to their own files, and web-search API keys move to your credential store. Rho prints what it moved and saves your original file as ~/.rho/config.toml.2x.bak. The TUI shows the same summary once. Upgrading from Rho 2.x lists every key.
A few settings need your attention:
- Hooks. If a hook's
toolslist namesedit, your hooks file fails to load withtool 'edit' is not in the canonical tool list. Replaceeditwithstr_replaceandapply_patch, and removecomputer. A hook that checks the payload's schema version must accept version 3 (Hooks). - Antigravity agents. In an Antigravity agent definition, replace
view_filewithread_fileandcreate_filewithwrite_file.
You can delete these leftovers. Rho 3 ignores them:
- an
[internal_agents.goal-judge]table ~/.rho/computer-use.toml~/.rho/computer-use-sessions/
Sessions
- Sessions from Rho 1.11 and later open in Rho 3. Older ones fail with
this session was created by rho before 1.11. Open those with Rho 2. - Rho 2 and Rho 3 can't use the same session at once. If you try, Rho 3 says the session
is open in another Rho process; close it there first. Rho 3 lets go of a session one to two minutes after its last activity.
Scripts
rho run --output jsonlwrites a new format, schema version2. Events such asrun.completedare gone. Read the final answer from theturn_endedevent instead (Automation output):bashrho run --output jsonl "summarize this repository" \ | jq -r 'select(.event.type == "turn_ended") | .event.outcome.text // empty'Subagent
result.jsonfiles name the session and model inruntime_session_idandruntime_model, notclaude_session_idandclaude_model.Workflow plan JSON uses
programandprogram_digestinstead ofgraphandgraph_digest. The error codelegacy_recordis nowunsupported_record. Top-level task names start withs0., for examples0.review(Workflows).Workflows saved before Rho 2.15 no longer open. Delete them from the
/workflowhub, or inspect them with Rho 2.
Removed
| Removed | Use instead |
|---|---|
/goal | State the outcome you want in your prompt. |
Computer use: /computer, rho computer, and the computer tool | Nothing. |
The hashline edit format | str_replace, the default, or apply_patch. Rho 3 switches edit_tool = "hashline" to "str_replace" for you. |
The old rho attach, which showed a subagent's files | rho attach <id>, or /attach in the TUI. |
| MCP sampling, where an MCP server asks Rho to run the model | Nothing. The sampling setting still loads but does nothing. |
Things to watch for
rho daemon stopandrho daemon restartstop running turns, and the commands and background processes your sessions started.- The daemon keeps the proxy settings (
HTTPS_PROXYand similar) andRHO_LOGit started with. After you change them, runrho daemon stop. The nextrhocommand starts the daemon with your shell's values. On Linux,rho doctorwarns when they differ. - A
--no-savesession exists only in memory. Quitting the TUI cancels its turn, and a daemon restart loses it.
Updating Rho 3 later
When you update Rho, with rho update, the install script, Cargo, or pacman, the daemon switches to the new version once nothing is running.
- With mise, run
rho daemon restartafter the update, once your work is done. - On Windows,
rho updateasks you to stop the daemon first. Runrho daemon stoponce your work is done, then the update command it printed.
rho uninstall also stops the daemon and interrupts running turns (The daemon and services).
Going back to Rho 2
Stop the daemon:
bashrho daemon stopInstall the last Rho 2 release. With the install script, set
RHO_VERSIONto it, for example:bashcurl -fsSL https://matthewyjiang.github.io/rho/install.sh | RHO_VERSION=2.34.0 shWith Cargo, run
cargo install rho-coding-agent --version 2.34.0.Restore your Rho 2 config:
bashcp ~/.rho/config.toml.2x.bak ~/.rho/config.tomlThis also brings back your web-search keys, which the backup still holds.
Rho 2 cannot open sessions that Rho 3 saved to. Use the copies you made before upgrading.
If you build on Rho's Rust libraries, the changelog lists their API changes.