Hermes Agent Deep Cuts: Your Model Changed, So Did Its Reasoning Budget
A single agent.reasoning_effort: high can mean different things after a model switch. Hermes checks for a model-specific override first, and that override follows the model across CLI sessions, gateway turns, cron, and fallback activation. One policy can keep a cheap route cheap while preserving deeper reasoning for the model that earns it.
That is useful when a fleet mixes models. It is also a quiet source of drift: the model you think is running at high may have a matching override at low, even when the global setting says otherwise.
The model is part of the setting
The resolver lives in hermes_constants.py. resolve_reasoning_config() looks for the active model in agent.reasoning_overrides, then falls back to agent.reasoning_effort. If neither setting resolves, Hermes leaves the choice to the provider. Session-level /reasoning --session overrides take precedence in gateway sessions.
Model matching is deliberately forgiving. Hermes tries the exact identifier, dot and dash variants, provider-stripped forms, and common provider prefixes. A key such as claude-opus-4-5 can match a request for claude-opus-4.5. For a slash-qualified model, exact qualified matches are checked before less specific forms.
This resolution is shared rather than reimplemented in every surface. The source calls it from CLI startup, the gateway, TUI, cron scheduler, and model-switch paths. The point is operational: switching to a fallback model can also switch the reasoning setting, because reasoning is resolved for the model that will actually receive the request.
The documented standard levels are none, minimal, low, medium, high, xhigh, max, and ultra. Hermes parses a bare string strictly. A typo such as hgih does not get sent as a custom tier. It fails resolution and falls through to the next configured source, which can make a bad override look like it was ignored.
Put effort where the model needs it
Set a global default, then override only the model routes that need a different level:
agent:
reasoning_effort: medium
reasoning_overrides:
"openrouter/anthropic/claude-opus-4.5": xhigh
"openai/gpt-5": low
"claude-sonnet-4.6": high
The same setting can be written with the CLI, but model identifiers containing dots need care because config set treats dots as path separators. Escape the model’s decimal point in a literal key:
hermes config set agent.reasoning_effort medium
hermes config set 'agent.reasoning_overrides.openai/gpt-5' low
hermes config set 'agent.reasoning_overrides.ollama-local/qwen3\.6:27b-q4_k_m' high
For a one-off run, use --reasoning without changing the profile:
hermes chat --reasoning high --query-file ./review-prompt.txt
That explicit launch choice is for that run. It does not rewrite the default or per-model map. This is the clean way to test whether a higher effort changes a particular task before changing your steady-state policy.
The custom-provider case needs a different representation. Hermes accepts only its standard ladder as a bare string. If the endpoint expects a tier such as thinking or fast, configure the explicit dictionary form in config.yaml:
agent:
reasoning_overrides:
"my-relay/lumo-max":
enabled: true
effort: thinking
That dictionary form passes the tier through verbatim. A plain reasoning_overrides: {"my-relay/lumo-max": thinking} does not. The documentation says the interactive /reasoning menu and setup picker expose the standard ladder, not custom names.
The gotcha is fallback, not just syntax
There are two easy ways to misread the result. First, an invalid bare override does not become an error at the model API. parse_reasoning_effort() returns no setting for an unrecognized string, so resolution can continue to the global value or provider default. A typo may therefore produce a valid request with a different effort than you intended.
Second, an explicit none is not the same as leaving the setting empty. Hermes represents none as reasoning disabled. An unset value means the provider can choose its own default. This matters for providers whose models default to substantial reasoning, and for endpoints that treat omission differently from an explicit disable.
Provider support still matters. The shared resolver decides what Hermes wants to request; the provider adapter decides what belongs on that provider’s wire. Hermes documents cases where unsupported reasoning parameters are omitted or retried without the field. A config value is not proof that the remote model received or honored it.
Verify the effective route
Start by checking what the installed CLI accepts and what the profile actually stores:
hermes chat --help | rg -A3 -- '--reasoning'
hermes config get agent.reasoning_effort
hermes config get agent.reasoning_overrides --json
Then compare the configured model with the matching override. The spelling-tolerant matcher means a key can apply even if its punctuation differs from the model string in a log. If you need to prove the resolver behavior outside a live provider call, the source tests exercise exact matches, spelling variants, provider prefixes, fallback to the global level, and invalid values in tests/test_hermes_constants.py.
For a real request, use verbose output or provider-side request logs to confirm the model and the field the endpoint received. Do not infer the effective effort from hermes config get agent.reasoning_effort alone. That command reports only the global value; it cannot tell you which per-model entry won, whether a session override is active, or whether the provider stripped an unsupported field.
The operator’s useful unit is not a global reasoning setting. It is a model route plus the override that resolves for it, checked again when fallback changes the route.