Skip to content

Configuration ​

Rho keeps agent settings in ~/.rho/config.toml by default. The interactive TUI reads two more files of its own: ~/.rho/clients/tui.toml for its display and composer settings, and ~/.rho/tui.toml for the theme and keybindings. RHO_HOME moves all three.

Change day-to-day settings from the TUI with /config, /model, /login, and the other commands below. Use this page for the file layout, CLI overrides, and keys that do not have their own page. A complete sample is in Configuration file example.

Secrets are never stored in config. See authentication and models.

Unknown keys and out-of-range values in any of these files are load errors. Rho reports every bad key at once, with its limit and the value you set. Rho 2.x clamped some values. Rho 3 does not.

Upgrading from Rho 2.x ​

Rho 2.x kept every setting in config.toml. Rho 3 splits them across three files. When Rho 3 starts and finds 2.x keys, it moves them and prints what it moved. The next TUI you open shows that summary once.

2.x keyRho 3 location
Every [display] key except themeTop level of clients/tui.toml
Top-level zen_mode, show_reasoning_output, max_tool_output_lines, check_for_updatesTop level of clients/tui.toml
behavior.check_for_updates, keybindings.editing_modeTop level of clients/tui.toml
display.theme, [keybindings] chordstui.toml
provider, model, auth, reasoning or reasoning_effort, fast_mode, favorite_models[model]
permission_mode, enable_subagents, inline_shell, rtk[behavior]
auto_compact, compact_threshold_percent, compact_target_percent[compaction]
max_output_bytes[output]
[title], title_provider, title_model, title_auth[internal_agents.session-title]
web_search_*_api_key, web_search.*_api_keyThe credential store
web_search.hosted, web_search.provider, web_search_providerweb_search.mode and web_search.backend
edit_tool = "hashline", in [behavior] or a custom provideredit_tool = "str_replace"
behavior.experimental_workspace_rewindRemoved
  • Rho first backs up each file it rewrites as <name>.2x.bak, or <name>.2x.bak.1 and so on if a backup exists. A backup keeps any plaintext web-search keys, so delete it once the upgrade looks right.
  • hosted = true with provider = "disabled" becomes mode = "off".
  • A value already set in tui.toml or clients/tui.toml wins.
  • Comments and key order stay for keys that do not move.
  • A key neither version knows stays put and is still a load error.

File layout ​

Every agent setting in config.toml lives in a table. Configuration file example has them all:

toml
[model]
provider = "openai"
model = "gpt-5.6-sol"
reasoning = "medium"

[behavior]
permission_mode = "supervised"
edit_tool = "auto"

[compaction]
auto_compact = true

[output]
max_output_bytes = 64000

[web_search]
mode = "auto"

The TUI's own settings sit at the top level of ~/.rho/clients/tui.toml:

toml
zen_mode = false
show_reasoning_output = true
output_streaming = "live"
show_header_hints = true
notifications = true
cache_miss_notices = false
max_tool_output_lines = 10
prompt_history_limit = 1000
editing_mode = "default"
check_for_updates = true

~/.rho/tui.toml holds the theme and keybindings. Restart the TUI after you edit it:

toml
theme = "terminal"

[keybindings]
cycle_permission_mode = "alt+m"

/config and --save rewrite only what you changed and keep your comments and formatting. A save that would leave the file invalid writes nothing.

Common settings ​

GoalWhere
Provider, model, reasoning[model], /model, or /config → Models
Theme, zen, reasoning display, output streaming~/.rho/tui.toml (theme), ~/.rho/clients/tui.toml, or /config → Display. See Theme, Transcript display, and Text streaming
Permission modePermission modes
Concurrent agents, subagents, rewindBehavior
Where session worktrees startGit
Questionnaire timeoutQuestionnaire timeout
Prompt templatesPrompt templates
Project and global instructionsAGENTS.md, /init, and /remember [global] <text>
Model-scoped system instructionsModel prompts
Web searchWeb search
SpaceXAI image generationSpaceXAI
Edit toolEdit tool
MCP servers[mcp.servers]. Inspect with /mcp or rho mcp list. See Model Context Protocol
OpenAPI sources[openapi.<source>]. See OpenAPI
Auto compactionAuto compaction
Per-model context or reasoningLocal model metadata
Model aliasesModel aliases
Internal agent modelsInternal agent models
Keybindings[keybindings] in ~/.rho/tui.toml. Restart required
Update checksUpdate checks
RTK rewriteRTK

Changing settings ​

/config saves settings through the daemon, and every open client sees the change. The root page starts with the current session's model, reasoning, fast mode, and permission mode, then lists these categories:

CategoryContains
ModelsDefault model, reasoning, and fast mode for new sessions
AgentPermission mode, Auto classifier, advisor, delegation, concurrent agents, questionnaire timeout, workspace rewind, cache warming
ContextAuto compaction and max output bytes
ToolsInline shell, edit tool, RTK, codemode, web search, SpaceXAI image generation
GitWhere session worktrees start
DisplayThe TUI's own settings in clients/tui.toml: zen mode, reasoning display, output streaming, header hints, notifications, cache miss notices, collapsed tool-output lines, prompt history, editing mode, update check

The theme and Clear prompt history at the bottom apply to this terminal only. To pick the credential store, run rho credential-store set (Credential store).

If a hand edit breaks the file, the TUI shows the error. Open sessions keep the last good settings, and new sessions fail to open until you fix it.

When a change applies:

  • Immediately: the Display settings, and concurrent agents.
  • From the next turn of each loaded session: advisor mode, the advisor model and reasoning, auto compaction, and the codemode mode.
  • New sessions: everything else, including the default model, permission mode, edit tool, and web search. /model, /permissions, and /fast change the current session.
  • Restart: keybindings and the theme in tui.toml.

/advisor turns the advisor on or off, and /advisor model picks its model. See Advisor mode.

When cache_miss_notices is on, a completed turn that re-billed a large uncached prompt, over 20K tokens or $0.10, inserts a transcript notice. /info always shows session and latest-request cache hit rates, plus re-billed totals once misses were counted.

show_header_hints controls the keyboard hint block under the session header. It defaults to on. Turning it off hides the shortcut list; a signed-out session still shows its /login hints.

notifications defaults to on. While the terminal is unfocused, Rho notifies when an approval or questionnaire opens or a turn finishes; queued follow-ups notify once, when Rho waits for you again. iTerm2, WezTerm, Ghostty, and kitty get an OSC 9 desktop notification. Other terminals, and anything inside tmux or screen, get a terminal bell. Rho only knows the terminal is unfocused if it reports focus changes; in tmux, set focus-events on. Under Herdr Rho sends none, because Herdr shows pane state itself.

Separately from notifications, Rho reports its state to terminals that support the Program Status Protocol (OSC 7501), such as Ghostty, so tabs and agent dashboards can show it:

StateWhen
workingA turn is running
blockedAn approval or questionnaire waits for you, or no provider is signed in
doneA turn finished
errorA turn failed and was not retried
idleRho started, or you interrupted or cancelled the turn

Like notifications, done and error are reported once Rho waits for you, so queued follow-ups do not report between turns. Rho clears its status on exit. Messages are the wait reason, the sign-in hint, or the first line of an error; prompts and assistant replies are never sent. Rho reports only after the terminal answers the protocol's support query at startup, and tmux and screen do not forward it. Set RHO_PROGRAM_STATUS=1 to report without asking, for example when SSH latency delays the reply, or RHO_PROGRAM_STATUS=0 to turn reports off.

/login, /logout, /refresh-models, and /model handle credentials, model lists, and the conversation model. Use /agents to inspect reserved internal agents and set their model overrides.

Project and global instructions ​

Rho loads instructions from AGENTS.md only. With the default system prompt, discovery runs in this order:

  1. Global instructions at ~/.rho/AGENTS.md.
  2. Project AGENTS.md files from the git root through the current working directory, including each directory on that path. Outside a git repository, only the current directory's AGENTS.md is discovered.

More specific files appear later and take precedence when instructions conflict. Rho does not load CLAUDE.md, .cursor/rules, or .github/copilot-instructions.md as instructions.

Run /init in the interactive TUI to survey the repository and create a concise AGENTS.md at its git root (or in the current directory outside a repository). The survey focuses on build/test/lint commands, layout, non-obvious conventions, and contribution rules. Existing instructions keep their structure and voice; /init makes targeted edits rather than replacing them. Other tools' instruction files may inform the survey, but the output is always AGENTS.md.

/init starts a model turn using a built-in skill and the active agent's file tools. It is unavailable during a running turn, in Plan permission mode, or when the active agent lacks the required skill, write, or file-edit tools. Normal write permissions still apply.

Instructions are cached for the current session and re-read from disk whenever you start or switch to a different session: /new (or /clear), /resume of another session, or cross-session tree selection. After /init or a manual instruction edit, start or switch sessions to load the updated global and project files, or restart Rho. Model switches and same-session tree navigation do not reload AGENTS.md. Added workspace directories load their own AGENTS.md files too. --no-system-prompt omits instruction files entirely.

Use /remember <text> in the interactive TUI to append one bullet to the Git-root AGENTS.md (or the current directory's file outside a repository). Use /remember global <text> for an instruction that applies across projects:

text
/remember use max jobs 8
/remember global keep explanations concise

The text must be a non-empty single line. Rho creates the file if needed, preserves existing instructions, and adds the new instruction to the current conversation without starting a model turn. The file is re-read whenever you start or switch to a different session, as described above. /remember is available only between model turns. To revise or remove instructions, edit AGENTS.md directly. Global instructions always live at ~/.rho/AGENTS.md, even when RHO_HOME redirects Rho's data directory.

CLI overrides ​

--provider, --model, --auth, and --reasoning override the loaded config for the current invocation. Add --save to write them as the future default.

bash
rho --provider openai --auth api-key --model gpt-5.6-sol
rho --reasoning high
rho --provider openai --auth api-key --model gpt-5.6-sol --save

Without --auth, a provider selected by --provider or a provider/model reference uses an auth mode that has a stored credential or RHO_<NAME>_API_KEY set, the same way the /model picker does. It falls back to the provider's default auth only when none does. For example, rho --model my-proxy/some-model run "hi" sends the key saved with /login my-proxy.

--config selects the file to load and save. It does not override those keys:

bash
rho --config ~/.rho/config.toml run "..."

The interactive TUI refuses --config, since its session runs in the daemon and uses the config in the daemon's Rho home. To use another config there, set RHO_HOME.

The exact --provider, --auth, and --model combination for each provider is on its provider page.

--no-system-prompt, --no-tools, --no-subagents, and --agent apply only to the current run and are not saved. --no-system-prompt and --no-tools must come before a subcommand (rho --no-tools run "..."). --no-subagents and --agent may appear before or after the subcommand. --no-subagents matches behavior.enable_subagents = false.

Reasoning options ​

model.reasoning is the thinking level: off, minimal, low, medium, high, xhigh, and max.

Rho reads each model's advertised effort values from cached models.dev metadata and skips the rest in the TUI. off stays available for every model. Rho omits reasoning by default, or sends effort: "none" when the model advertises that value. Override the list with supported_reasoning_levels in ~/.rho/models.toml. See Local model metadata.

For supported OpenAI Responses providers, off omits the reasoning object. Other levels send reasoning.summary = "auto" with the matching effort.

Local Ollama and config-defined OpenAI-compatible hosts send reasoning_effort, including "none", when capability metadata is missing or the model supports reasoning. Rho omits the field when metadata says reasoning is not configurable, because those APIs treat a missing field as thinking on. Switching models maps an unavailable level to the closest lower supported level. When metadata is missing or uses an unsupported scheme, Rho keeps the full list rather than guessing.

Whether reasoning text is shown, zen mode, and output streaming are display settings. See Transcript display and Text streaming.

Advisor mode ​

Advisor mode gives the agent an advisor tool backed by a second model. That model reviews the session transcript and has no tools of its own.

Details: Advisor mode.

Prompt templates ​

A Markdown or text file becomes a slash command. The filename is the command. The file contents are the prompt.

  • ~/.rho/prompts/review.md makes /prompt:review available everywhere.
  • .rho/prompts/review.md makes /prompt:review available in that project and its subdirectories.
  • A project file overrides a global file with the same name.
text
Review this code for correctness, security, and maintainability.

Inline config overrides a file with the same name:

toml
[prompt_templates]
review = "Review this code for correctness, security, and maintainability."

/prompt:review src/config.rs expands to the template text plus src/config.rs. Tab in the command palette expands without sending. Enter expands and sends. Names may contain letters, numbers, -, and _, and cannot duplicate built-in command names.

Placeholders put arguments inside the template instead of after it:

  • $ARGUMENTS is all text after the command.
  • $1, $2, … are the whitespace-separated arguments. Double quotes group words with spaces: /prompt:fix "login bug" src/auth.rs makes $1 = login bug. Single quotes stay literal, so apostrophes are safe.
  • A missing argument expands to nothing.
text
Compare $1 with $2. Focus on: $ARGUMENTS

A template with any placeholder no longer gets the text appended. Its palette entry lists the arguments it takes, such as /prompt:compare [$1] [$2] [arguments], and Tab completes the command so you can type them first. Template files reload while Rho runs: palette discovery is cached for 2 seconds, while submitting /prompt:<name> refreshes the files immediately. Inline [prompt_templates] changes apply after a restart.

Model aliases ​

[model.aliases] maps a short name to a concrete model so a pinned id lives in one place. A value is provider/model or a bare model id, which keeps whichever provider is otherwise selected. Model ids may contain /.

toml
[model.aliases]
deep = "anthropic/claude-opus-4-8"
fast = "gpt-5.6-luna"
openrouter-deep = "openrouter/anthropic/claude-sonnet-4"

Reference an alias with @. The prefix distinguishes aliases from concrete ids, so a missing alias is a configuration error.

toml
[model]
model = "@deep"

[internal_agents.session-title]
model = "@fast"

The same syntax works with rho --model @deep, /model @deep, and model: @deep in agent definition frontmatter. Rho resolves aliases before any model-specific behavior and never rewrites the mapping. A concrete model id is always literal, even when an alias has the same name. Saving config keeps the @deep reference rather than its expansion while the selected concrete model still matches. Alias values must be concrete models, so they cannot begin with @. Every provider-qualified alias is validated at load, including aliases that are not selected.

Local model metadata ​

~/.rho/models.toml overrides catalog fields for one model. RHO_HOME moves this file with the rest of ~/.rho. RHO_MODELS_PATH selects a different file.

Without this file, Rho uses the catalog window. For GPT-5.5 and GPT-5.6 that is the models.dev input limit. Codex GPT-5.5 keeps a 400k effective window because that is the product limit. Set usable_context_window to raise or cap the budget Rho shows and uses for auto compaction:

toml
[models."openai-codex/gpt-5.6-sol"]
usable_context_window = 272000

The key is provider/model. You can also set effective_context_window and supported_reasoning_levels. Set catalog to a models.dev provider slug, or to provider/model, to borrow that catalog row for a custom host. Local values win over catalog data. Restart Rho or switch models after you edit the file.

toml
[models."cliproxyapi/claude-sonnet-4-5"]
catalog = "anthropic"

[models."cliproxyapi/opus-thinking"]
catalog = "anthropic/claude-opus-4-6"

The catalog window can sit above a model's long-context price tier. Rho does not clamp it.

A custom host with catalog_mode = "model-id" looks up the unsplit slug/model id among models.dev serving providers first. When no provider publishes that id, as with alibaba/qwen3.8-flash-next, which only resellers serve, Rho falls back to the canonical models.dev model page for the same id. That entry fills the context window, output limit, image input, and whether the model reasons. It has no prices or effort values, so cost stays unknown and, for reasoning models, the picker keeps every level. Set catalog or the fields above in models.toml to fill the rest.

Image input comes from models.dev modalities.input. When the catalog lists a model as text-only, Rho replaces images from read_file, MCP tools, and attachments with a short text note before sending the request. Models with no catalog row still receive images. Set image_input to override the catalog:

toml
[models."cliproxyapi/my-text-model"]
image_input = false

Internal agent models ​

Rho uses reserved internal agents for session titles, the advisor tool, Auto permission classification, and compaction summaries. Most roles follow the active conversation provider, model, and auth. Run /agents, select the role, and press Enter to choose a model. Use conversation model removes that role's override. Changes apply to the next invocation and save at once.

advisor and permission-classifier have no default and no conversation-model fallback. Advisor mode stays inactive until a model is chosen. Interactive startup opens the classifier picker for Auto when no model is set; cancelling it falls back to Supervised. The classifier defaults to low reasoning when a model is first selected.

The advisor picker also lists claude-code/… rows when claude-agent-acp is installed. Choosing one runs the advisor on Claude Code. When the advisor model supports configurable reasoning, Rho carries the previous level, or the advisor default, onto the new model.

/config → Agent exposes advisor model, advisor reasoning, permission classifier model, and permission classifier reasoning.

toml
[internal_agents.session-title]
provider = "openai"
model = "gpt-5.6-luna"
auth = "api-key"

Model aliases work here.

The same table sets the model of a read-only plugin agent; /agents writes it when you pick one. An entry applies by ID to any Rho agent Rho does not reserve, so it also reaches an agent file of your own with that ID.

Edit tool ​

edit_tool under [behavior] selects the file edit tool exposed to the model. It defaults to auto. Only one edit tool is registered at a time.

ValueExposed toolFormat
autopreferred for the active providerBuilt-in catalog. Switches when the provider changes
apply_patchapply_patchCodex-style, multi-file patch documents
str_replacestr_replaceExact old_string to new_string replacement in one file
toml
[behavior]
edit_tool = "auto"

auto is a preference, not a tool name. Rho keeps auto in config and advertises the concrete format the active provider's models were trained on. Custom providers can override that choice:

toml
[providers.custom.vllm]
base_url = "http://127.0.0.1:8000/v1"
edit_tool = "apply_patch"

Built-in providers have no per-provider override. They use this table unless you pin a global behavior.edit_tool.

ProviderPreferred formatWhy
openai-codexapply_patchCodex trains on Codex-style patches
anthropicstr_replaceClaude Code trains on exact string replace
xaistr_replaceFirst-party agent tooling uses string replace
all othersstr_replaceRho default when no first-party match is known

Pinned values stay fixed across provider changes. A change from /config applies to new sessions. Auto also switches live when you change providers mid-session. Rho 3 removed the hashline format, and the 2.x upgrade rewrites it to str_replace. Format details: Edit formats.

Behavior ​

These keys live under [behavior].

enable_subagents controls the agent and agents tools. It defaults to true. Set it to false to remove both tools and tell the model not to delegate. The change applies to the next session. --no-subagents does the same for one run.

agent_concurrency is the maximum number of delegated agents that may run at once, including background runs. It defaults to 10 and must stay between 1 and 64. A change applies immediately. Running agents keep their slots, and queued agents start in order as slots free up. The daemon shares this budget across all its sessions (Subagents). RHO_AGENT_CONCURRENCY is no longer read. Claude-cli runs also take a nested cap of 2 by default (RHO_CLAUDE_AGENT_CONCURRENCY), always min(total, claude_cap). Cursor runs take only the global pool. There is no nested Cursor cap yet.

inline_shell selects the shell for ! and !! in the TUI. It defaults to bash on macOS and Linux and powershell on Windows. See inline shell.

workspace_rewind enables native file-tool checkpoints and /rewind. It defaults to true. Toggle /config → Agent → Workspace rewind, or opt out explicitly:

toml
[behavior]
workspace_rewind = false

Restart Rho after changing it. Checkpoints from the old experimental version lack pre-turn conversation boundaries and cannot be rewound; they are rejected before any files change.

Checkpoints capture original file contents for write and the selected native edit tool. Shell (bash), process, Git, network, database, service, and other untracked tool effects are not captured; recorded untracked effects show a limited badge in /rewind. /tree changes conversation state only. /rewind restores captured files and returns the conversation to before the selected turn, preserving the old branch. Conflicting or unsupported paths stay unchanged; a partial restore does not select a different conversation state.

Checkpoint journals live at <session>/workspace-checkpoints/checkpoints.jsonl. The per-file capture budget is 2 MiB: larger files are marked unsupported, and a transcript notice names the budget, limit, and file size. The serialized per-session journal budget is 64 MiB: a turn that would exceed it is not appended, and a visible notice names the budget, limit, requested total, and turn size. Further capture pauses for that running session; earlier turns remain rewindable. See workspace checkpoints for storage and privacy details.

advisor_mode controls whether the advisor tool is available. It defaults to false. See Advisor mode.

Git ​

These keys live under [git].

worktree_from_remote decides where a session worktree starts. It defaults to true: Rho fetches the origin remote's default branch (origin/main, say) and starts the worktree's branch there, so a session starts from what the remote has even when your checkout is behind. Without an origin, or when the fetch fails or takes over 30 seconds, the worktree starts from HEAD. Set it to false to always start from your checkout's HEAD, as before:

toml
[git]
worktree_from_remote = false

Toggle it in /config → Git. The change applies to the next worktree.

Codemode ​

The codemode tool composes native and MCP sibling tools in a Starlark script. It is available whenever tools are enabled. [codemode] mode matches Pi's codemode.mode and controls how the other tools are presented:

toml
[codemode]
mode = "on" # or "only"
  • on (default): native sibling tools such as read_file, write, and bash stay declared next to codemode; the model may use either.
  • only: only codemode and tool_search are declared by default. Native siblings remain executable through script call_tool; top-level tool_search can explicitly load its matches for direct calls on the next model request.

/codemode on|only changes the next model request without rebuilding the runtime and saves the preference. Neither mode is a permission level: nested calls inherit permission_mode. MCP tools start deferred in both modes. Top-level tool_search loads only its returned matches, making them directly callable with full argument schemas on the next model request. Script-side search_tools, list_tools, and describe_tool remain read-only: they do not load tools, but scripts can call discovered tools immediately without loading direct schemas. See Codemode for the discovery and loading distinction.

Scripts call one tool with call_tool(name, args) or run independent calls concurrently with call_tools([(name, args), ...]), which returns results in order. Pass exact tool names and argument dictionaries. Results are native Starlark dictionaries with "is_error", "content", and "data" keys; use bracket indexing, not dot access. A batch runs up to 4 calls at once, the same width as a model-issued parallel tool batch, and the whole batch counts toward the 64-call limit per script before any call starts. Script list_tools() and search_tools(query) return {name, description} rows; describe_tool(name) adds the parameter and data schemas. A script that fails keeps its printed output and call log. See Codemode for the full guide.

RTK ​

behavior.rtk enables built-in RTK command rewriting when the rtk binary is available. It defaults to true. Set it to false to leave shell commands unchanged.

Tool output limit ​

output.max_output_bytes is how much output Rho keeps from tool calls such as command output, file reads, and loaded skills. It defaults to 64000 and must be at least 1.

max_tool_output_lines in ~/.rho/clients/tui.toml is how many wrapped screen rows of a tool card show inline before the TUI collapses the rest. It defaults to 10 and must be at least 1. Delegated agent prompts use the same limit: they stream from the beginning, then keep a stable collapsed preview. Click the card or press Ctrl+O to expand the full prompt while it streams or after launch. Once the agent starts or finishes, run receipts and results appear before the prompt so they remain visible when collapsed.

prompt_history_limit in ~/.rho/clients/tui.toml is how many sent composer prompts Rho keeps in ~/.rho/prompt-history.sqlite3 for up-arrow recall across sessions. $RHO_HOME moves that file. It defaults to 1000, at most 10000, and 0 disables persistence. Edit it in /config → Display → Prompt history limit. Lowering it deletes the oldest extras. Clear prompt history on the root page of /config clears the history after asking. This is separate from /new and /clear, which reset the conversation, not composer recall.

Update checks ​

check_for_updates in ~/.rho/clients/tui.toml controls whether Rho checks the latest GitHub release at TUI startup. It defaults to true. A newer version shows an update notice in the session header and points to rho update.

Questionnaire timeout ​

Questionnaires wait for an answer by default. To let an untouched form use explicit fallback answers, set a positive whole number of seconds:

toml
[questionnaire]
timeout_seconds = 60

That value is an example, not a default. Omit timeout_seconds to disable automatic answers. Zero, negative values, fractions, and strings are invalid. In /config → Agent → Questionnaire timeout, enter positive seconds, or clear the field to remove it. A change applies to new sessions.

The session enforces the timeout even with no client attached, using the value it opened with. Once you start filling in the form, it waits for your answer.

What the TUI shows, and what does not count as consent: Questionnaire fallbacks.