Configuration reference

Oh My Herdr reads a TOML configuration file. This page describes version 0.2.18 configuration behavior and defaults. The generated template is available with omh --default-config.

File and state paths

Configuration path precedence

The configuration file is selected in this order:

A debug source build uses the application directory name omh-dev in these derived paths. A release build uses omh.

OMH_CONFIG_PATH wins over all directory variables and may point outside the derived configuration directory. Relative paths in ui.sound.path, ui.sound.done_path, and ui.sound.request_path are resolved relative to the selected configuration file's parent directory.

State paths

State uses a separate platform path and has no OMH_CONFIG_PATH override:

The configuration directory contains the default session snapshot at session.json. Named session data is under sessions/<name>/. The state directory stores state such as plugin state, agent-detection manifest caches, and product-announcement state. The exact files in those directories are runtime data, not configuration keys.

Loading, missing files, and diagnostics

• A missing configuration file loads built-in defaults and produces no diagnostic.
• A configuration read error loads built-in defaults and records a read diagnostic.
• A TOML parse error loads built-in defaults and records a parse diagnostic.
• A valid file with an unknown top-level table records a diagnostic. The loader does not promise strict schema validation for every unknown key or nested value.
• Invalid values can produce diagnostics while the corresponding value or section falls back to a default or remains unchanged during a live reload.

omh config check reads the selected file and prints either config: ok or each diagnostic. It returns 0 when no diagnostics are reported and 1 when diagnostics are reported. A usage error returns 2. See the CLI reference.

Reload and startup application

Configuration reload is available through omh server reload-config and the configured in-app reload action (default prefix+shift+r). The server returns one of these statuses:

omh server reload-config prints the JSON response. A successful API response, including a report whose status is partial, exits 0; a server/API error exits 1. The in-app reload reports the same status in its configuration diagnostics surface.

Reload is section-oriented rather than an all-or-nothing schema validation pass. For example, a bad [keys] section can leave current keybindings in place while a valid [theme] section is applied. Invalid [ui] sidebar bounds (sidebar_min_width > sidebar_max_width) retain the previous UI section. Sound-file diagnostics and keybinding diagnostics can produce partial while other valid settings are applied.

Top-level settings

onboarding

[theme]

The built-in name, light, and dark values are theme names such as catppuccin, catppuccin-latte, dracula, nord, gruvbox, tokyo-night, and the other names included in omh --default-config. A name is resolved separately for light and dark appearance.

[theme.custom] keys

Each custom color is a string. Accepted color forms are #rrggbb, #rgb, a named color, rgb(r,g,b), and reset aliases where supported.

[terminal]

[session]

[keys]

Key binding syntax and the full interactive binding surface are described in the keybinding reference. A binding accepts one string or an array of strings. Empty strings and empty arrays leave optional actions unset.

[keys.indexed] contains:

Each [[keys.command]] entry contains:

[ui]

[ui.sidebar]

Agent-row tokens are state_icon, state_text, workspace, tab, pane, agent, terminal_title, terminal_title_stripped, and custom tokens beginning with $. Space-row tokens are state_icon, state_text, workspace, branch, git_status, and custom tokens beginning with $. A layout can contain at most 16 rows and 16 tokens per row. Unknown built-in tokens, invalid custom token names, and unknown canonical agent IDs are diagnostics.

[ui.toast]

The legacy ui.toast.enabled boolean is accepted for compatibility and maps to delivery = "omh" when true or delivery = "off" when false, unless an explicit delivery is present.

[ui.sound]

Agent sound override keys are pi, claude, codex, gemini, cursor, agy, cline, open_code, github_copilot, devin, kimi, kiro, droid, amp, grok, hermes, kilo, qodercli, and maki. Each accepts default, on, or off; every key defaults to default except droid, which defaults to off. Sound paths must resolve to existing MP3 files; invalid, missing, or non-MP3 files are diagnostics and use the default sound.

[worktrees]

[git]

[update]

[agent_profiles]

Each [[agent_profiles.custom]] entry has:

System profiles are catalogued from detected supported agent kinds. A custom profile with an invalid command or invalid environment entries is retained as a profile diagnostic and is not launchable.

[remote]

This setting is read when a remote bridge starts. It does not change an already running SSH bridge through configuration reload.

[advanced]

[experimental]

These settings are experimental runtime controls. Their names and behavior can change between releases.

Accepted cjk_ime_agents names are pi, claude, codex, gemini, cursor, cline, opencode, copilot, devin, kimi, kiro, droid, amp, grok, hermes, kilo, qodercli, qoder, and maki.

Diagnostics and invalid sections

Diagnostics identify read failures, TOML parse failures, unknown top-level tables, invalid key combinations, invalid sidebar bounds, invalid sound files, and other value problems detected by the current loader. Diagnostics are not a statement that every unknown nested key is rejected by a strict schema validator.

During a live reload, a syntactically unreadable file has status failed and leaves the current live configuration intact. A readable file with invalid sections has status partial: valid sections may apply, while the invalid section keeps its previous live value. A file with no diagnostics has status applied.