Skip to main content

​
Accessing settings

To configure droid settings:
  1. Run droid
  2. Enter /settings
  3. Adjust your preferences interactively
Changes take effect immediately and are saved to your settings file.

​
Where settings live

OSLocation
macOS / Linux~/.factory/settings.json
Windows%USERPROFILE%\.factory\settings.json
If the file doesn’t exist, it’s created with defaults the first time you run droid.

​
Available settings

SettingOptionsDefaultDescription
modelsonnet, opus, GPT-5, gpt-5-codex, gpt-5-codex-max, haiku, droid-core, custom-modelopusThe default AI model used by droid
reasoningEffortoff, none, low, medium, high (availability depends on the model)Model-dependent defaultControls how much structured thinking the model performs.
autonomyLevelnormal, spec, auto-low, auto-medium, auto-highnormalSets the default autonomy mode when starting droid.
cloudSessionSynctrue, falsetrueMirror CLI sessions to Factory web.
diffModegithub, unifiedgithubChoose between split GitHub-style diffs and a single-column view.
completionSoundoff, bell, fx-ok01, fx-ack01, or custom file pathfx-ok01Audio cue when a response finishes.
awaitingInputSoundoff, bell, fx-ok01, fx-ack01, or custom file pathfx-ack01Audio cue when droid is waiting for user input.
soundFocusModealways, focused, unfocusedalwaysWhen to play sound notifications.
commandAllowlistArray of commandsSafe defaults providedCommands that run without extra confirmation.
commandDenylistArray of commandsRestrictive defaults providedCommands that always require confirmation.
includeCoAuthoredByDroidtrue, falsetrueAutomatically append the Droid co-author trailer to commits.
enableDroidShieldtrue, falsetrueEnable secret scanning and git guardrails.
hooksDisabledtrue, falsefalseGlobally disable all hooks execution.
ideAutoConnecttrue, falsefalseAuto-connect to IDE from external terminals.
todoDisplayModeinline, pinnedpinnedHow the todo list is displayed in the UI.
specSaveEnabledtrue, falsefalsePersist spec outputs to disk.
specSaveDirFile path.factory/docsDirectory used when specSaveEnabled is true.
enableCustomDroidstrue, falsetrueToggle the Custom Droids feature.
showThinkingInMainViewtrue, falsefalseDisplay AI thinking/reasoning blocks in the main chat view.
allowBackgroundProcessestrue, falsefalseAllow droid to spawn background processes (experimental).
enableReadinessReporttrue, falsefalseEnable the /readiness-report slash command (experimental).

​
Model

Choose the default AI model that powers your droid:
  • opus - Claude Opus 4.5 (current default)
  • sonnet - Claude Sonnet 4.5, balanced cost and quality
  • gpt-5.1 - OpenAI GPT-5.1
  • gpt-5.1-codex - Advanced coding-focused model
  • gpt-5.1-codex-max - GPT-5.1-Codex-Max, supports Extra High reasoning
  • gpt-5.2 - OpenAI GPT-5.2
  • haiku - Claude Haiku 4.5, fast and cost-effective
  • gemini-3-pro - Gemini 3 Pro
  • droid-core - GLM-4.6 open-source model
  • custom-model - Your own configured model via BYOK
You can also add custom models and BYOK.

​
Reasoning effort

reasoningEffort adjusts how much structured thinking the model performs before replying. Available values depend on the model, but typically include:
  • off / none – disable structured reasoning (fastest).
  • low, medium, high – progressively increase deliberation time for more complex reasoning.
Anthropic models default to off, while GPT-5 starts on medium.

​
Autonomy level

autonomyLevel controls how proactively droid executes commands when sessions begin. Start at normal, or select an auto-* preset to pre-authorize additional actions.

​
Diff mode

Control how droid displays code changes:
  • github – Side-by-side, higher fidelity render (recommended).
  • unified – Traditional single-column diff format.

​
Cloud session sync

When this switch is on, every CLI session is mirrored to Factory web so you can revisit conversations in the browser:
  • true – Sync sessions to the web app.
  • false – Keep sessions local only.

​
Sound notifications

Configure audio feedback for droid events: Completion sound (completionSound) - plays when a response finishes:
  • fx-ok01 – Built-in completion sound (default) - soft success bloop
  • fx-ack01 – Alternative built-in sound effect - tactile ripple feedback
  • bell – Use the system terminal bell
  • off – No sound notifications
  • Custom path – Provide a file path to your own sound file (e.g., "/path/to/sound.wav")
Awaiting input sound (awaitingInputSound) - plays when droid is waiting for user input. Same options as completion sound, defaults to fx-ack01. Sound focus mode (soundFocusMode) - controls when sounds play:
  • always – Play sounds regardless of window focus (default)
  • focused – Only play sounds when the terminal is focused
  • unfocused – Only play sounds when the terminal is not focused
Access sound settings via /settings or Shift+Tab → Settings in the TUI.

​
Hooks

The hooksDisabled setting provides a global toggle to disable all hooks execution without removing your hook configurations:
  • false – Hooks are enabled and will execute normally (default)
  • true – All hooks are disabled globally
You can also toggle this from the /hooks menu or /settings.

​
IDE auto-connect

The ideAutoConnect setting controls whether droid automatically connects to your IDE when running from external terminals (outside the IDE’s built-in terminal):
  • false – Only auto-connect when running inside IDE terminal (default)
  • true – Auto-connect to IDE from any terminal

​
Todo display mode

The todoDisplayMode setting controls how the todo list is displayed in the UI:
  • pinned – Todo list is pinned above the input area (default)
  • inline – Todo list appears inline within the message flow

​
Command allowlist & denylist

Use these settings to control which commands droid can execute automatically and which it must never run:
  • commandAllowlist – Commands in this array are treated as safe and run without additional confirmation, regardless of autonomy prompts. Include only low-risk utilities you rely on frequently (for example ls, pwd, dir).
  • commandDenylist – Commands in this array always require confirmation and are typically blocked because they are destructive or unsafe (for example recursive rm, mkfs, or privileged system operations).
Commands that appear in both lists default to the denylist behavior. Any command that is in neither list falls back to the autonomy level you selected for the session.

​
Example allow/deny configuration

{
  "commandAllowlist": [
    "ls",
    "pwd",
    "dir"
  ],
  "commandDenylist": [
    "rm -rf /",
    "mkfs",
    "shutdown"
  ]
}
Review and update these arrays periodically to match your workflow and security posture, especially when sharing configurations across teams.

​
Example configuration

{
  "model": "opus",
  "reasoningEffort": "low",
  "diffMode": "github",
  "cloudSessionSync": true,
  "completionSound": "fx-ok01",
  "awaitingInputSound": "fx-ack01",
  "soundFocusMode": "always",
  "todoDisplayMode": "pinned"
}

​
Need more?