Skip to content

docs: align reasoning-effort values and model references #1199

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
TheFactoriousDROID wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: align reasoning-effort values and model references #1199

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dc42bf8
docs: align reasoning-effort values with available models
TheFactoriousDROID Jun 7, 2026
7a20c75
docs: keep choosing-your-model out of the reasoning-effort branch
TheFactoriousDROID Jun 7, 2026
7f20910
docs: correct reasoning-effort notes on settings page
TheFactoriousDROID Jun 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 24 additions & 13 deletions docs/cli/configuration/settings.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,8 @@ Local overrides merge on top of the corresponding `settings.json` at the same le

| Setting | Options | Default | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- | -------------------------------------------------------------------------- |
| `model` | Any [available model ID](/models) | Product default | The default AI model used by droid |
| `reasoningEffort` | `off`, `none`, `low`, `medium`, `high` (availability depends on the model) | Model-dependent default | Controls how much structured thinking the model performs. |
| `sessionDefaultSettings.model` | Any [available model ID](/models) | Product default | The default AI model used by droid |
| `sessionDefaultSettings.reasoningEffort` | Reasoning value (model-dependent) — see [Reasoning effort](#reasoning-effort) | Model-dependent default | Controls how much structured thinking the model performs. |
| `sessionDefaultSettings.interactionMode` | `auto`, `spec` | `auto` | Sets whether new sessions start in Auto or Spec Mode. |
| `sessionDefaultSettings.autonomyLevel` | `off`, `low`, `medium`, `high` | `off` | Sets the default [Autonomy Level](/cli/user-guides/auto-run) for new sessions. |
| `cloudSessionSync` | `true`, `false` | `true` | Mirror CLI sessions to Factory web. |
Expand All @@ -65,16 +65,25 @@ Local overrides merge on top of the corresponding `settings.json` at the same le

### Model

Set `model` to a [model ID from Available Models](/models). For custom models, see [Bring Your Own Key (BYOK)](/cli/byok/overview).
Set `sessionDefaultSettings.model` to a [model ID from Available Models](/models). For custom models, see [Bring Your Own Key (BYOK)](/cli/byok/overview).

<Note>For backward compatibility, `model`, `reasoningEffort`, `autonomyMode`, `specModeModel`, and `specModeReasoningEffort` are also accepted as top-level keys; droid migrates them into `sessionDefaultSettings` on load. New configurations should nest them under `sessionDefaultSettings`.</Note>

### Reasoning effort

`reasoningEffort` adjusts how much structured thinking the model performs before replying. Available values depend on the model, but typically include:
`sessionDefaultSettings.reasoningEffort` controls how much structured thinking the model performs before replying. The model picker and the [Available Models](/models) **Reasoning** column show these levels as display labels; use the matching value below in `settings.json`:

- **`off` / `none`** – disable structured reasoning (fastest).
- **`low`**, **`medium`**, **`high`** – progressively increase deliberation time for more complex reasoning.
| Label | `settings.json` value |
| ------------ | --------------------- |
| Off / None | `off` / `none` |
| Minimal | `minimal` |

@factory-droid factory-droid Bot Jun 7, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P1] Reconcile reasoningEffort values across docs (missing dynamic)

docs/enterprise/hierarchical-settings-and-org-control.mdx documents sessionDefaultSettings.reasoningEffort as allowing dynamic, but the new table here omits it; please reconcile by either adding dynamic (if valid for settings.json) or explicitly calling out that dynamic is enterprise/API-only and not accepted in local CLI settings to avoid contradictory guidance.

| Low | `low` |
| Medium | `medium` |
| High | `high` |
| Extra High | `xhigh` |
| Max | `max` |

Anthropic models default to `off`, while GPT-5 starts on `medium`.
Higher effort increases latency and cost. Which levels are available — and which is the default — depend on the model, so check the **Reasoning** column in [Available Models](/models). Display labels can vary slightly by surface (for example, `max` may appear as **Max** or **Maximum**).

### Autonomy level

Expand Down Expand Up @@ -162,7 +171,7 @@ Defaults applied when a new session starts. See also `sessionDefaultSettings.int
| Setting | Type | Options | Default | Description |
| ------------------------------------------------ | ------ | ---------------------------------------- | -------------- | ---------------------------------------------------------- |
| `sessionDefaultSettings.specModeModel` | string | Any [available model ID](/models) | Inherits model | Override the model used when sessions start in Spec Mode. |
| `sessionDefaultSettings.specModeReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | Model default | Reasoning effort applied to the spec model. |
| `sessionDefaultSettings.specModeReasoningEffort` | string | See [Reasoning effort](#reasoning-effort) | Model default | Reasoning effort applied to the spec model. |

## Display and UI

Expand Down Expand Up @@ -192,13 +201,13 @@ Configure [Missions](/cli/features/missions) — multi-agent orchestration runs.
| Setting | Type | Options | Default | Description |
| ---------------------------------------------------- | ------- | ---------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------- |
| `missionModelSettings.workerModel` | string | Any [available model ID](/models) | Inherits | Default model used by mission worker subagents. |
| `missionModelSettings.workerReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | Model default | Reasoning effort for mission workers. |
| `missionModelSettings.workerReasoningEffort` | string | See [Reasoning effort](#reasoning-effort) | Model default | Reasoning effort for mission workers. |
| `missionModelSettings.validationWorkerModel` | string | Any [available model ID](/models) | Inherits | Model used by mission validators (scrutiny / user-testing workers). |
| `missionModelSettings.validationWorkerReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | Model default | Reasoning effort for validation workers. |
| `missionModelSettings.validationWorkerReasoningEffort` | string | See [Reasoning effort](#reasoning-effort) | Model default | Reasoning effort for validation workers. |
| `missionModelSettings.skipScrutiny` | boolean | `true`, `false` | `false` | Skip scrutiny validation milestones during missions. |
| `missionModelSettings.skipUserTesting` | boolean | `true`, `false` | `false` | Skip user-testing validation milestones during missions. |
| `missionOrchestratorModel` | string | Any [available model ID](/models) | Inherits | Model used by the mission orchestrator. |
| `missionOrchestratorReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | Model default | Reasoning effort for the mission orchestrator. |
| `missionOrchestratorReasoningEffort` | string | See [Reasoning effort](#reasoning-effort) | Model default | Reasoning effort for the mission orchestrator. |
| `keepSystemAwakeDuringMissions` | boolean | `true`, `false` | `true` | Prevent the OS from sleeping while a mission is running. |

## Context and compaction
Expand Down Expand Up @@ -254,8 +263,10 @@ System-level settings for status line, worktrees, and request timeouts.

```json
{
"model": "claude-opus-4-7",
"reasoningEffort": "low",
"sessionDefaultSettings": {
"model": "claude-opus-4-8",
"reasoningEffort": "high"
},
"diffMode": "github",
"cloudSessionSync": true,
"completionSound": "fx-ok01",
Expand Down
12 changes: 6 additions & 6 deletions docs/reference/cli-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ Customize droid's behavior with command-line flags:
| Flag | Description | Example |
| :-------------------------------- | :----------------------------------------------------------------- | :----------------------------------------------------------- |
| `-f, --file <path>` | Read prompt from a file | `droid exec -f plan.md` |
| `-m, --model <id>` | Select a specific [model ID](/models) | `droid exec -m claude-opus-4-7` |
| `-m, --model <id>` | Select a specific [model ID](/models) | `droid exec -m claude-opus-4-8` |
| `-s, --session-id <id>` | Continue an existing session | `droid exec -s session-abc123` |
| `--auto <level>` | Set [autonomy level](#autonomy-levels) (`low`, `medium`, `high`) | `droid exec --auto medium "run tests"` |
| `--enabled-tools <ids>` | Force-enable specific tools (comma or space separated) | `droid exec --enabled-tools ApplyPatch,Bash` |
Expand All @@ -66,8 +66,8 @@ Customize droid's behavior with command-line flags:
| `-o, --output-format <format>` | Output format (`text`, `json`, `stream-json`, `stream-jsonrpc`) | `droid exec -o json "document API"` |
| `--input-format <format>` | Input format (`stream-jsonrpc` for multi-turn) | `droid exec --input-format stream-jsonrpc -o stream-jsonrpc` |
| `-r, --resume [sessionId]` | Resume a previous session. In interactive mode, `-r` is `--resume`; in `droid exec`, `-r` is `--reasoning-effort`. | `droid -r` |
| `-r, --reasoning-effort <level>` | Override reasoning effort (`off`, `none`, `low`, `medium`, `high`). In `droid exec`, `-r` maps to this flag. | `droid exec -r high "debug flaky test"` |
| `--spec-model <id>` | Use a different [model ID](/models) for specification planning | `droid exec --spec-model claude-opus-4-7` |
| `-r, --reasoning-effort <level>` | Override reasoning effort; valid values are model-dependent (see [Reasoning effort](/cli/configuration/settings#reasoning-effort)). In `droid exec`, `-r` maps to this flag. | `droid exec -r high "debug flaky test"` |
| `--spec-model <id>` | Use a different [model ID](/models) for specification planning | `droid exec --spec-model claude-opus-4-8` |
| `--spec-reasoning-effort <level>` | Override reasoning effort for spec mode | `droid exec --use-spec --spec-reasoning-effort high` |
| `--use-spec` | Start in specification mode (plan before executing) | `droid exec --use-spec "add user profiles"` |
| `--skip-permissions-unsafe` | Skip all permission prompts (⚠️ use with extreme caution) | `droid exec --skip-permissions-unsafe` |
Expand All @@ -78,8 +78,8 @@ Customize droid's behavior with command-line flags:
| `--fork <id>` | Fork and resume an existing session into a new copy | `droid exec --fork session-abc123` |
| `--mission` | Run `droid exec` in [mission mode](/cli/features/missions) (multi-agent orchestration) | `droid exec --mission -f mission.md` |
| `--worker-model <id>` | Model used for mission worker agents | `droid exec --mission --worker-model claude-sonnet-4-6` |
| `--worker-reasoning-effort <level>` | Reasoning effort for mission worker agents (`off`, `none`, `low`, `medium`, `high`) | `droid exec --mission --worker-reasoning-effort medium` |
| `--validator-model <id>` | Model used for mission validator agents | `droid exec --mission --validator-model claude-opus-4-7` |
| `--worker-reasoning-effort <level>` | Reasoning effort for mission worker agents (model-dependent; see [Reasoning effort](/cli/configuration/settings#reasoning-effort)) | `droid exec --mission --worker-reasoning-effort medium` |
| `--validator-model <id>` | Model used for mission validator agents | `droid exec --mission --validator-model claude-opus-4-8` |
| `--validator-reasoning-effort <level>` | Reasoning effort for mission validator agents | `droid exec --mission --validator-reasoning-effort high` |
| `--append-system-prompt <text>` | Append custom text to the end of the system prompt | `droid --append-system-prompt "Always run tests."` |
| `--append-system-prompt-file <path>` | Append the contents of a file to the end of the system prompt | `droid --append-system-prompt-file .factory/system.md` |
Expand Down Expand Up @@ -149,7 +149,7 @@ The interactive REPL supports a rich set of keyboard shortcuts for navigation, o
| `Ctrl+J` | Toggle the changelog display (dismiss / restore) |
| `Ctrl+E` | Toggle the approval details view |
| `Ctrl+V` | Paste an image from the clipboard as an attachment |
| `Tab` | Cycle reasoning effort (`low` → `medium` → `high` → `off`) |
| `Tab` | Cycle reasoning effort through the levels supported by the current model |

@factory-droid factory-droid Bot Jun 7, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P1] Update other shortcut docs to match new Tab reasoning-effort behavior

This changes Tab to “cycle through the levels supported by the current model”, but docs/cli/user-guides/become-a-power-user.mdx still claims a fixed cycle (low → medium → high → off); aligning those docs will prevent users from assuming missing levels (e.g., minimal, xhigh, max) are unreachable via the TUI.

| `Shift+Tab` | Cycle interaction modes (Auto → Spec → Mission) |
| `@` | File path autocomplete — typing `@` triggers fuzzy file search |
| `Up` / `Down` | Navigate input history (cycle through previously submitted messages) |
Expand Down
Loading