---
name: rho-config
description: Configure Rho settings, providers, models, credentials, permissions, tools, global instructions, and ~/.rho/config.toml.
---
# Rho configuration
Help the user configure rho. Determine what they want to change, then guide them to the right mechanism. Prefer the interactive `/config` browser or direct config-file edits over telling the user to run one-off commands, unless a command is the natural fit.
## The global `~/.rho` directory
`~/.rho` is rho's home data and settings directory. `RHO_HOME` overrides its data location, but global instructions, loose skills, and agent definition discovery still use the home-directory paths below. What lives there:
- `config.toml` - persistent settings (see below).
- `AGENTS.md` - your global instructions, applied to every session (see below).
- `agents/` - user-defined agents (for example `~/.rho/agents/planner.md`).
- `skills/` - skills available only to rho.
- `prompts/` - prompt template files; each filename becomes a slash command.
- `hooks.toml` - user hooks, always eligible.
- `models.toml` - local model catalog overrides (or the file `RHO_MODELS_PATH` selects). Use this to set a per-model `usable_context_window`, `supported_reasoning_levels`, or `catalog` slug.
- `credentials/` - secrets when the `file` credential backend is selected (`credentials/secrets.json`).
- `sessions/` - saved session transcripts and workspace keys.
- `subagents/` - global delegated runs.
- `usage.sqlite3` - the usage ledger.
- `prompt-history.sqlite3` - sent composer prompts for up-arrow recall across sessions.
- `cache/`, `web-access/`, `workflows/` - cached and runtime data; do not edit these by hand.
`RHO_HOME` also moves the usage ledger and other data roots. Credentials and the ledger live under `$RHO_HOME` too.
## The global `AGENTS.md`
`~/.rho/AGENTS.md` holds instructions that apply to every rho session regardless of project. It is loaded as a project-instruction file before any project `AGENTS.md`, so project files appear later and take precedence on conflict. Edit it to set house rules that should always apply: prose style, commit conventions, safety boundaries, build hygiene, or any standing policy. Keep it focused; everything in it is injected into the system prompt for every session.
For a quick addition in the interactive TUI, use `/remember global <text>` to append one bullet to `~/.rho/AGENTS.md`, or `/remember <text>` for the project-root `AGENTS.md` (the Git root, or the current directory outside a repository). The text must be a non-empty single line. These commands run between model turns, write the file locally, and add the instruction to the current conversation without a model response. The file is re-read when you start or switch to a different session (`/new`, `/resume` of another session, or the next launch). Global instructions stay at `~/.rho/AGENTS.md` even when `RHO_HOME` redirects data.
To revise or remove instructions, edit `~/.rho/AGENTS.md` directly with the file tools, or open it for the user and make the edit. Offer a concrete draft when the user describes a rule in prose. Project `AGENTS.md` files live at `<project>/AGENTS.md`; the global file sits in the home directory, not in any project.
For project onboarding, `/init` surveys the repository and creates or updates `AGENTS.md` at the git root (or current directory outside a repository). It preserves existing files with targeted edits and requires write permission; it is unavailable in Plan mode. Rho loads project `AGENTS.md` files from the git root through the current directory, with more specific files taking precedence. `AGENTS.md` is the only instruction filename; `CLAUDE.md` is not supported. After `/init` or any manual global/project instruction edit, run `/new` or restart Rho to reload the files. Model switches keep the cached instructions.
## Where settings live
Rho stores persistent config at `~/.rho/config.toml` by default. `RHO_HOME` overrides the config directory; `rho --config <path>` loads and saves a specific file. Restart-only settings are the values the running process used at startup, so a config edit does not take effect until rho starts again. Some settings apply live; say which one you are recommending.
## The four ways to configure
1. **Interactive TUI**: `/config` opens a category browser (Models, Appearance, Agent behavior, Context & limits, Tools, Providers). Type to filter, press `enter` to open a category, press `space` to toggle an on/off setting, and `esc` to return. `/login`, `/logout`, `/model`, and `/agents` are direct shortcuts. This is the easiest path for a user already in the TUI.
2. **Command line**: `--provider`, `--model`, `--auth`, and `--reasoning` update the config file and become the future default. `rho credential-store` shows or sets the credential backend.
3. **Direct file edit**: edit `~/.rho/config.toml` by hand. Group settings by purpose. Use this for settings the TUI does not expose, such as `[model.aliases]`, `[internal_agents]` overrides, `[prompt_templates]`, `[keybindings]`, `[providers.ollama].base_url` (also set by `/login ollama`), and `[providers.custom.<name>].base_url` / `catalog` / `catalog_mode` / `api` / `edit_tool`. Per-model context windows, reasoning lists, and catalog rematches live in `~/.rho/models.toml`, not `config.toml`.
4. **Environment**: `RHO_CREDENTIAL_STORE=os|file` overrides the saved credential backend; `RHO_MODELS_PATH` selects a custom models file; `RHO_TRUST_PROJECT_AGENTS=1`, `RHO_TRUST_PROJECT_HOOKS=1`, and `RHO_TRUST_PROJECT_PLUGINS=1` trust project agent definitions, hooks, and Agent Plugins.
## Inspect the current live config
Use the read-only `rho` tool with action `config` to see the sanitized live configuration (model, provider, reasoning, compaction, edit tool, web search, update checks, subagents, rtk, output limits). It excludes credentials and user content. It reports the values the running process uses; restart-only settings may differ from what is saved for the next startup.
## Common tasks
- **Set the default model or provider**: use `/model provider/model` in the TUI, or `rho --provider <provider> --model <model> --auth <auth>`. For the exact `--provider`/`--auth`/`--model` combination a provider expects, check the provider page.
- **Change reasoning**: cycle `reasoning` (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`) in `/config` under Models, or set it in config. `reasoning` applies to the current session. Change `show_reasoning_output`, `zen_mode`, and `theme` under Appearance; those apply immediately when changed through `/config`. Direct configuration-file edits take effect on the next startup.
- **Manage credentials**: `/login [provider]` and `/logout [provider]`. The credential backend is `behavior.credential_store` (`os` or `file`). When unset, rho asks where to store secrets at first login.
- **Model aliases**: define `[model.aliases]` in config and reference them with an `@` prefix, for example `model = "@deep"`. Alias values must be concrete models and cannot begin with `@`. Update the alias table in one place to change the model everywhere it is referenced.
- **Per-model context window**: edit `~/.rho/models.toml` (not `config.toml`). Example: `[models."openai-codex/gpt-5.6-sol"]` with `usable_context_window = 272000` to cap, or a larger value to raise. Restart rho or switch models after editing.
- **Internal agent models**: use `/agents`, select `session-title` or `goal-judge`, and press `enter` to choose a model, or edit `[internal_agents.<role>]` in config. Pick **Use conversation model** to remove an override.
- **Permission mode**: `permission_mode` must be `bypass`, `auto`, `allow_edits`, `plan`, or `supervised`. `allow-edits` is accepted as an alias of `allow_edits`. Set it under Agent behavior in `/config`, or in config. `bypass` allows every capability. `auto` uses the same write and process gate as `allow_edits` and classifies only the requests that gate does not allow. `allow_edits` allows in-workspace writes to git-tracked, non-symlink files and later writes to a path already allowed this session. Untracked and gitignored paths, writes outside the workspace, and process execution still ask first. `plan` denies file writes and process execution. `supervised` asks before file writes and process execution. The change applies before the next turn and clears session approvals.
- **Workspace rewind**: on by default for saved interactive sessions. Toggle **Workspace rewind** under Agent behavior in `/config`, or set `[behavior] workspace_rewind = false` to opt out; restart Rho to apply. The old experimental key is ignored. Checkpoints capture native file-tool mutations, not shell/process effects, and contain unredacted original file contents under `<session>/workspace-checkpoints/checkpoints.jsonl`. The per-file capture budget is 2 MiB (oversized files are unsupported with a notice); the serialized session journal budget is 64 MiB (a rejected append pauses capture with a visible budget notice; earlier checkpoints remain rewindable). `/rewind` restores conversation state to before the selected turn, preserving the old branch.
- **Auto compaction**: under Context & limits in `/config`. `compact_target_percent` must stay below `compact_threshold_percent`; values at or above the threshold are clamped.
- **Cache miss notices**: under Appearance in `/config`, or `display.cache_miss_notices` in config. Off by default. When on, a completed turn that re-billed a large uncached prompt (over 20K tokens or $0.10) inserts a transcript notice naming the likely cause (model switch, idle past the cache TTL, or unattributed). `/info` always reports cache hit rate and re-billed totals.
- **Header hints**: under Appearance in `/config`, or `display.show_header_hints` in config. On by default. Off hides the keyboard hint block under the session header; a signed-out session still shows its `/login` hints.
- **Notifications**: under Appearance in `/config`, or `display.notifications` in config. On by default. While the terminal is unfocused, an approval, questionnaire, or finished turn sends an OSC 9 desktop notification (iTerm2, WezTerm, Ghostty, kitty) or a bell (other terminals, tmux, screen). Needs terminal focus reporting (`focus-events on` in tmux). Never sent under Herdr, which shows pane state itself.
- **Web search**: under Tools in `/config`. `web_search.mode` is `auto` (native if supported, otherwise the selected backend), `backend` (force that backend), or `off`. `web_search.backend` selects `openai`, `exa`, `brave`, or `firecrawl`; failures never switch services. Each backend has its own `api_base_url`. OpenAI explicitly selects `api` or fixed-endpoint `codex`; Exa selects `api` or `mcp` with a separate `mcp_url`. Store keys in the credential editor or environment. Firecrawl Cloud requires a key; custom selfhost URLs can omit auth. TUI changes apply before the next turn, preserving an active turn's route and credentials. Direct file edits require restart. Test connection asks before sending a potentially billed query, even in Auto or Off mode.
- **Edit tool**: under Tools in `/config`, choose `auto`, `hashline`, `apply_patch`, or `str_replace`. Exactly one edit schema is exposed under its own tool name (`edit`, `apply_patch`, or `str_replace`). `auto` keeps that preference in config and advertises the preferred format for the active provider, switching live when the provider changes. Prefer `auto` so models get the edit tool their first-party harness trained them on (Codex → `apply_patch`, Anthropic/SpaceXAI → `str_replace`, otherwise Rho `hashline`). Pinned formats stay fixed. The change applies before the next turn: the tool list rebuilds and the session gets a short notice with the new tool schema. It cannot change while a model turn is running.
- **Prompt templates**: add a file under `~/.rho/prompts/` or `<project>/.rho/prompts/`, or define `[prompt_templates]` inline in config. The filename or key becomes the slash command. Restart rho after adding or editing templates.
- **Global instructions**: add a standing rule with `/remember global <text>` between turns, or edit `~/.rho/AGENTS.md` to revise or remove rules (see above). Use `/remember <text>` for project-only instructions.
- **Keybindings**: edit `[keybindings]` in config. Values use `+`-separated modifiers and keys. Keybinding changes take effect at startup.
## Applying a change
`[questionnaire].timeout_seconds` is optional positive whole seconds. Omission disables automatic answers; zero is invalid. `/config` → Agent behavior → Questionnaire timeout edits the same setting, with an empty field for Disabled. It applies when a form opens. Only forms with explicit model `on_timeout` fallback answers can time out; defaults never authorize a timeout. Interaction pauses it for the rest of that form. Never use fallbacks for authorization or destructive decisions.
State which mechanism you recommend and, when relevant, when it takes effect. Settings that apply to the current session or the next turn need no restart, including TUI web search changes, `advisor_mode`, `edit_tool`, and `agent_concurrency`; `enable_subagents`, templates, and keybindings apply on the next session or at startup. When the user edits config directly, tell them a restart may be required and offer to check whether the setting is restart-only. `agent_concurrency` is under Agent behavior in `/config` (Concurrent agents) or `behavior.agent_concurrency` in config; it defaults to 10, max 64, and applies immediately. `RHO_AGENT_CONCURRENCY` is no longer read.