Skip to content

Thinking ​

Many models can reason before they answer. somora has one setting for how much: off, low, medium or high. It works the same on every engine, and somora translates it into the word each model expects.

What you get ​

  • One setting for all engines. The same four levels on Claude, Codex, Grok and local models.
  • A default per agent, a choice per session. Set the level in agent.yaml and change it for one session with /thinking.
  • Words that fit the model. A mapping per model turns high into xhigh or max where the model calls it that.
  • An honest badge. The header shows the level, the word the model receives, and whether the model can reason at all.
  • The reasoning itself. Where the engine provides it, the thinking text appears above the reply, next to a count of reasoning tokens.

Try it ​

In the TUI or the web client, type:

/thinking high           # more reasoning for this session
/thinking off            # no reasoning
/thinking default        # back to the agent's default
/thinking                # TUI: show the level and where it comes from

Ask something that needs thought and watch the 🧠 count next to the output tokens. Then compare with /thinking low.

To set an agent's default, add one line to its agent.yaml:

yaml
model: opus
thinking: medium     # off | low | medium | high

Where the level comes from ​

The first source that has a value wins.

OrderSourceSet with
1The session/thinking <level>, or the THINKING section of the ••• session menu in the web client
2The agentthinking: in agent.yaml
3The modelreasoning.default of the model in config.yaml; for a builder, builder.thinking of the model when set
4Nothing setsomora sends no level and the model uses its own default

In the TUI, /thinking - does the same as /thinking default: it removes the session's level, and the next source applies.

"Nothing set" is not "off". Many reasoning models think by default, Qwen 3.x among them, so an agent without a level runs them at full depth. Every client shows this state as model decides, never as off. What "nothing set" means per model family, and which default fits, is listed under When no level is set. To make "off" (or any level) the rule for a model, give it a default:

yaml
providers:
  gpu-box:
    models:
      - id: my-thinking-model
        alias: thinker
        capabilities: [text, reasoning]
        reasoning:
          default: "off"          # sent when session and agent set nothing
          levels: { "off": none, high: high }

The default is written in somora's words (off, low, medium, high) and goes through the model's levels like any other level. It applies on every engine. The session menu, /thinking and the phone's model sheet name it as the model's default.

The reasoning capability ​

The level only reaches a model that lists reasoning in its capabilities in config.yaml:

yaml
- id: claude-opus-5-5
  alias: opus
  contextWindow: 1000000
  capabilities: [text, image, pdf, reasoning]

Without reasoning, somora sends no thinking parameter and the model behaves as it does by default. The level stays stored and the header marks it as dormant.

Cloud reasoning models support it. Plain local models (Gemma, plain Llama or Mistral) do not. Local reasoning models served by vLLM or SGLang (GPT-OSS, Qwen thinking models, DeepSeek) do: mark them with reasoning and the same setting works there.

What each engine receives ​

somora levelclaude-clicodex-cligrok-cliopenai-compatible
offthinking: { type: 'disabled' }turn/start.effort: minimal--reasoning-effort lowparameter omitted
loweffort: 'low'turn/start.effort: low--reasoning-effort lowreasoning_effort: 'low'
mediumeffort: 'medium'turn/start.effort: medium--reasoning-effort mediumreasoning_effort: 'medium'
higheffort: 'high'turn/start.effort: high--reasoning-effort highreasoning_effort: 'high'

What off means differs per engine:

  • Claude really switches thinking off.
  • Codex has no off. It gets minimal, its lowest word.
  • Grok always reasons. It gets low.
  • OpenAI-compatible models get no parameter, which is the model's own default. For Qwen 3.x that default is thinking on. For DeepSeek V4 on SGLang it is no reasoning at all.

The table is the default. A reasoning.levels block on the model replaces single cells for codex-cli, grok-cli and openai-compatible. It has no effect on claude-cli.

Mapping levels per model ​

Models disagree on the words, and some reject a word they do not know. Each model in config.yaml may carry a reasoning: block that says which word somora sends for each level:

yaml
providers:
  local:
    engine: openai-compatible
    models:
      - id: some-qwen-reasoning-model
        alias: qwen
        contextWindow: 262144
        capabilities: [text, reasoning]
        maxTokens: 16384              # output cap, reasoning included
        reasoning:
          param: reasoning_effort     # reasoning_effort (default) | reasoning | chat_template_kwargs
          levels:                     # somora level: word the model gets
            off: null                 # null = omit the parameter
            low: low
            medium: medium
            high: xhigh               # this model's real maximum
      - id: some-deepseek-model
        capabilities: [text, reasoning]
        reasoning:
          levels: { medium: high, high: max }
KeyMeaning
levels.<level>A string is sent as it is. null omits the parameter for that level. A level you leave out keeps the default from the table above.
paramWhere the word goes in the request. Only for openai-compatible.
paramRequest bodyUsed by
reasoning_effort (default){ "reasoning_effort": … }OpenAI, vLLM, LiteLLM
reasoning{ "reasoning": { "effort": … } }OpenRouter
chat_template_kwargs{ "chat_template_kwargs": { "reasoning_effort": … } }vLLM templates that only read kwargs

On Codex the GPT-5.6 family also accepts xhigh and max, so reasoning: { levels: { high: xhigh } } sends effort: xhigh for /thinking high. somora codex debug models lists the words each Codex model accepts.

Tip

max is meant for the hardest problems, with the latency and cost to match. Map it when you need it, not as a default.

Note

somora reads the config as YAML 1.2, so an unquoted off: key is the string off. Quoting it ("off": low) is equally fine and safer for tools that read the file as YAML 1.1.

What the model families accept ​

Model familyAccepted wordsAn unknown word
OpenAI o-series, gpt-5none minimal low medium high xhighanswers 400
Qwen 3.x reasoning (vLLM chat template)none low medium xhigh, no highanswers 400
DeepSeek V4low high max. none and no parameter both mean no reasoning.is ignored
DeepSeek V4.1none low high max. Map off: none and medium: high.is ignored

The models guide has the recommended mapping for each tested model, GLM included.

Switching Qwen off ​

Without a mapping, off sends nothing and Qwen 3.x keeps thinking. There are two ways to map it:

MappingResultUse it for
off: noneZero reasoning tokens. About one reply in eight then opens with planning text ("The user asks … I can answer that directly …").Workers whose output is parsed, not read
off: lowAbout 110 extra tokens per reply, in the thinking channel where they belong. No planning text in the reply.Agents that talk to people

chat_template_kwargs: { enable_thinking: false } is the same switch as none at the template level. On a backend without none, off: low is the floor anyway. somora does not guess this for you.

DeepSeek V4 on SGLang ​

This model reasons only when the request carries a reasoning_effort. With the parameter omitted it answers without a thinking phase, and any thinking lands in the visible text. So off really is off there, and every other level switches thinking on.

When a model rejects the word ​

With or without a mapping, a backend may answer with an error about the effort value. somora then retries once:

  1. It reads the list of accepted words from the error message, for example "Supported: xhigh, medium, low".
  2. It picks the nearest weaker word, or else the nearest stronger one. It never picks none.
  3. It sends the request again. The adjusted word stays for the rest of the turn.

On openai-compatible, a rejected none is retried with the parameter omitted, never with a word that thinks. The same happens when the error names no words. On codex-cli the retry only happens when the error lists the words. A model that knows no minimal then gets low for off.

The chat shows a "reasoning effort adjusted" line with what was sent. That is the cue to add the word to the model's levels, so it stops costing a round trip.

Models behind a router ​

The retry needs the backend's error to reach somora. A gateway that normalises parameters, such as LiteLLM with drop_params: true, often drops reasoning_effort before the model sees it. Every level then answers normally with the same amount of reasoning, and the badge shows a word that never arrives.

  • Fix it on the router. In LiteLLM, let the parameter through for that route, for example with allowed_openai_params: ["reasoning_effort"]. Neither the retry nor levels can help while the router drops it.
  • Check with a direct probe. Send two efforts with a prompt that needs thinking and compare usage.completion_tokens_details.reasoning_tokens.
  • Map the model explicitly. A router may still hide the error for an unknown word, so do not rely on the retry there.

Dream phases ​

The background workers for REM, Deep and Lucid have their own optional level. They use the same engine mapping, the same reasoning.levels and the model's maxTokens output cap. On openai-compatible workers the retry applies too.

PhaseFileSetting
REMagent.yamlrem.thinking
REM judgeconfig.yamlrem.dedup.judge.thinking
Deepconfig.yamlwiki.deep.thinking
Lucidconfig.yamlwiki.lucid.thinking

Unset means no level is sent and the model decides. A Qwen 3.x worker then thinks. A high level is a reasonable choice here: nobody waits for the answer, and the cost is longer runs and more tokens.

REM is set per agent because extraction differs by persona. Deep and Lucid work on the wiki that all agents share, so they are set once.

What the header shows ​

BadgeMeaning
🧠 mediumThe level is applied.
🧠 high→xhighApplied, and the model receives a different word than the level. 🧠 high→off means the parameter is omitted.
thinking=medium (dormant)A level is stored, but the model has no reasoning capability. It has no effect.
🧠 autoWeb client: nothing is set on a reasoning model, so the model decides.
thinking with a spinnerTUI only: the turn runs and no reply text has arrived yet.
↓ 412 (1.2k 🧠)Reasoning tokens of the turn, next to the output tokens.
(~1.2k 🧠)The same as an estimate, see below.

The TUI and the web client show the same badges. Three differences: the web client hides the badge when the level is off, shows 🧠 auto when nothing is set, and the TUI shows the arrow only on openai-compatible models. Dream runs are background work and have no badge.

Reasoning tokens ​

EngineCount shownSource
codex-cliyesreasoningOutputTokens in the app-server's thread/tokenUsage/updated notification
openai-compatibleyescompletion_tokens_details.reasoning_tokens in the usage chunk
grok-cliyesreasoningTokens in the usage Grok reports at the end of the turn
claude-clinoAnthropic counts thinking inside output_tokens. There is no separate number.

Some OpenAI-compatible backends stream the reasoning text but report no reasoning_tokens (SGLang, some routers). somora then estimates the count from the streamed text, about four characters per token, and marks it with a tilde. An exact count from the backend always wins.

Seeing the thinking text ​

The reasoning text travels as its own event, separate from the reply. It is never sent back to a model: history rebuilds, compaction summaries and REM extraction read user, assistant and tool rows only.

ClientWhat you seeSwitch
WebA collapsed 🧠 thinking block above the reply. While the model thinks and has not written yet, it is open and shows the last lines live. It folds when the reply starts. Click to open it.Show thinking in replies in the ••• session menu, or /verbose thinking on|off. On by default, remembered per session in the browser.
TUIThe text dimmed and indented above the reply, at most 40 lines (… (+N lines)), and the last lines live while the model thinks./verbose thinking on|off. Off by default. tui.verbose.thinking in config.yaml sets the start value.
MobileOne 🧠 thinking row. Tap it to read all of it.none

The client switches only change the display. The text is still captured, stored and exported.

What each engine provides ​

EngineYou getChecked
openai-compatibleThe full reasoning text, when the backend streams reasoning_content or reasoning deltas.end to end on DeepSeek V4 (SGLang) and Qwen 3.8 (vLLM) through a LiteLLM router
openai-compatible, inline <think> modelsThe full text, split off the reply.DeepSeek V4 Flash
claude-cliWhatever the Claude Agent SDK delivers. With the current SDK the thinking blocks arrive empty, and somora shows one placeholder line saying that the model thought. A redacted block gets its own placeholder.yes
codex-cliA summary per thinking phase: heading-like sentences. Codex never streams the raw reasoning. somora asks for summary: auto on turn/start while capture is on and reads item/reasoning/summaryTextDelta.yes
grok-cliWhat Grok streams as ACP agent_thought_chunk: short notes on its plan, live while it works, each model round in its own paragraph.yes

In practice the full text comes from local and routed models. Claude, Codex and Grok give a placeholder, a summary or short notes, because their providers do not disclose the trace.

Models that think inline ​

Some models print their reasoning as <think>…</think> inside the normal text: DeepSeek V4 on a server without a reasoning parser, R1, QwQ. somora splits the block off. The reasoning goes to the thinking block, and the reply and any subagent result stay clean.

Both shapes are handled: the full block, and the one where the chat template already wrote <think> into the prompt, so only the closing tag arrives. Until the closing tag arrives, the text may stream as reply text. The final message is always clean.

Settings ​

Server-wide, in config.yaml. The values shown are the defaults.

yaml
thinkingContent:
  capture: true
  maxChars: 65536
SettingDefaultMeaning
thinkingContent.capturetruefalse drops the thinking text at the server: no SSE event, no JSONL row, nothing in any client. Codex is then asked for no summaries.
thinkingContent.maxChars65536Most characters of thinking text stored per turn. Longer text is cut and the clients show "(truncated by the server)". Keeps a long reasoning phase from filling the session file.
tui.verbose.thinkingfalseWhether the TUI starts with the thinking text shown.

Where a level is set:

SettingFileValues
thinkingagent.yamloff, low, medium, high. Unset: nothing is sent.
rem.thinkingagent.yamlthe same
rem.dedup.judge.thinking, wiki.deep.thinking, wiki.lucid.thinkingconfig.yamlthe same
reasoning.defaultper model in config.yamloff, low, medium, high. Used when session and agent set nothing. Unset: nothing is sent.
reasoning.param, reasoning.levelsper model in config.yamlsee Mapping levels per model

Commands ​

CommandWhereWhat it does
/thinkingTUIShows the level, its source, and a warning when it is dormant.
/thinking off|low|medium|highTUI, webSets the level for this session.
/thinking defaultTUI, webRemoves the session's level.
/verbose thinking on|offTUI, webShows or hides the thinking text.

Routes ​

MethodPathPurpose
GET/agents/:agent/sessions/:session/thinkingThe level in effect and its source
PUT/agents/:agent/sessions/:session/thinkingBody { "level": "high" }. Sets the session's level. Answers { agent, session, level }, or 400 for an unknown level.
DELETE/agents/:agent/sessions/:session/thinkingRemoves the session's level. Answers { agent, session, cleared: true }.

All three answer 404 for an unknown agent or session. A GET response:

json
{
  "agent": "<your-agent>",
  "session": "main",
  "effective": "high",
  "override": "high",
  "personaDefault": "medium",
  "modelDefault": "off",
  "source": "session-override",
  "modelSupportsReasoning": true,
  "wire": "xhigh"
}
FieldMeaning
effectiveThe level in effect, or null when nothing is set.
overrideThe session's level, or null.
personaDefaultThe agent's level, or null.
modelDefaultThe active model's reasoning.default, or null.
sourcesession-override, persona-default, model-default, or engine-default (nothing set: nothing is sent, the model decides).
modelSupportsReasoningfalse means the level is dormant.
wireThe word the engine sends when it differs from effective, else null. "off" means the parameter is omitted. Reported for openai-compatible and codex-cli.

Events ​

The agent SSE event carries the thinking state at the start and the end of a turn, so a client can show the badge from the first token:

jsonc
event: agent
data: {
  "phase": "start",
  "provider": "local",
  "model": "some-qwen-reasoning-model",
  "thinking": { "level": "high", "active": true, "wire": "xhigh" }
}
jsonc
event: agent
data: {
  "phase": "end",
  "usage": {
    "tokens_in": 12450,
    "tokens_out": 387,
    "tokens_in_cached": 11800,
    "tokens_out_reasoning": 1240,
    "tokens_out_reasoning_estimated": true
  },
  "contextWindow": 262144,
  "provider": "local",
  "model": "some-qwen-reasoning-model",
  "thinking": { "level": "high", "active": true, "wire": "xhigh" }
}
FieldMeaning
thinkingPresent only when a level is set.
thinking.activefalse: the model lacks the reasoning capability and the level is dormant.
thinking.wireThe word sent when it differs from level. "off" means the parameter is omitted. Sent for openai-compatible models only.
usage.tokens_out_reasoningReasoning tokens of the turn, when the engine reports or somora estimates them.
usage.tokens_out_reasoning_estimatedtrue when the count is an estimate. Absent otherwise.

The thinking text has its own event and its own history row:

WhereShape
SSEevent: thinking with { state: 'delta' | 'final', text, truncated? }. Deltas are cumulative, like chat. The final arrives before the chat final of the same turn.
JSONL and /chat/historyOne thinking_message row per turn, placed before the turn's assistant_message. Deltas are not stored.
A rejected effort wordAn engine_meta row of type reasoning_effort_adjusted.

Troubleshooting ​

The badge says dormant. The model has no reasoning in its capabilities. Add it if the model can reason, or switch the model.

The level changes nothing. If the model sits behind a router, the router probably drops the parameter. See Models behind a router.

/thinking off and the model still thinks. On Qwen 3.x, off sends nothing unless you map it. See Switching Qwen off.

Replies open with planning text. The model runs with none. Map off: low for that model.

A "reasoning effort adjusted" line in the chat. The model rejected the word. The server log has engine.reasoning_effort_rejected with the backend's text. Add the word it accepts to the model's levels.

No thinking block on Claude, only a placeholder. That is what the SDK delivers. The setting still works.

See also ​

  • Models: tested models and the mapping each one needs
  • Sampling: temperature, top_p and friends, set the same way
  • TUI display: /verbose and what the header shows
  • Dream phases: REM, Deep and Lucid
  • Models: maxTokens and other model settings
  • API: all routes and SSE events