Settings

This is the reference for settings.json, the personal CLI configuration file. It covers the settings you control as an individual developer. Settings that are typically managed by an organization (model policy, network restrictions, autonomy ceilings, and similar hard controls) are listed in a clearly labeled section below and documented in full in Enterprise Controls & Managed Settings. For personal session defaults managed in the Factory App, see App settings.

Accessing settings

To configure droid settings:

1. 1
   Run droid
2. 2
   Enter /settings
3. 3
   Adjust your preferences interactively

Changes take effect immediately and are saved to your settings file.

Where settings live

If the file doesn't exist, it's created with defaults the first time you run droid.

Local overrides

You can create a settings.local.json alongside settings.json in any .factory/ folder:

• ~/.factory/settings.local.json (user-level)
• <project>/.factory/settings.local.json (project-level)

Local overrides merge on top of the corresponding settings.json at the same level and follow the same hierarchy precedence. Add settings.local.json to .gitignore if you want to keep machine-specific preferences out of version control.

Legacy Droid YAML configuration

.droid.yaml was an older project configuration surface. Use the current .factory/ files instead:

• Use settings.json and settings.local.json for Droid preferences and local overrides.
• Use AGENTS.md for repository instructions, conventions, and validation commands.
• Use MCP servers, hooks, and skills for integrations, automation, and reusable workflows.

Available settings

Model

Set model to a model ID from Factory-Managed Inference. For custom models, see Custom Models (BYOK).

Reasoning effort

reasoningEffort adjusts how much structured thinking the model performs before replying. The available levels and the default are set by each model, so the Available Models table is the source of truth for what a given model accepts. Across the catalog they range from least to most deliberation:

• off / none: no structured reasoning (fastest).
• dynamic: use the model's dynamic reasoning behavior.
• minimal, low, medium, high: progressively more deliberation.
• xhigh, max: the deepest reasoning, where a model offers it.

Each model accepts only the subset shown in its Available Models row, and its default sits within that subset (for example, Claude Opus 4.8 defaults to high, while Claude Sonnet 4.5 defaults to off).

Autonomy level

Use sessionDefaultSettings.interactionMode to choose whether new sessions start in Auto or Spec Mode, and sessionDefaultSettings.autonomyLevel to set the default Autonomy Level. off keeps manual approvals; low, medium, and high pre-authorize work at or below that risk level.

sessionDefaultSettings.autonomyMode is deprecated and retained for older configurations.

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.

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.

Set showHookOutput to true when you want hook stdout and stderr to appear in the session transcript for debugging.

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

Command allowlist, denylist & blocklist

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). A denied command can still be run if you explicitly approve it.

commandBlocklist

Commands in this array can never run. Unlike the denylist, there is no prompt and no way to approve them: the block applies even under full autonomy, auto-run, or --skip-permissions-unsafe. droid also resolves the actual program being invoked, so a blocked command cannot be slipped through with a wrapper shell, an absolute path, quoting tricks, or command substitution.

Commands that appear in both the allowlist and denylist default to the denylist behavior. The blocklist always takes precedence over both. Any command that is in none of the lists falls back to the autonomy level you selected for the session.

Example allow/deny/block configuration

{
  "commandAllowlist": ["ls", "pwd", "dir"],
  "commandDenylist": ["rm -rf /", "mkfs", "shutdown"],
  "commandBlocklist": ["shutdown", "mkfs", "curl"]
}

Use commandBlocklist for commands that should be hard-stopped regardless of approvals; use commandDenylist for commands that are allowed only after explicit confirmation. Review and update these arrays periodically to match your workflow and security posture, especially when sharing configurations across teams.

Session defaults

Defaults applied when a new session starts. See also sessionDefaultSettings.interactionMode and sessionDefaultSettings.autonomyLevel in the table above.

Display and UI

Tune how droid renders content in the terminal.

toolResultDisplaystringdefault: expanded

How tool results are rendered in the transcript. Options: expanded, compact.

showTokenUsageIndicatorbooleandefault: false

Show the live token usage indicator at the bottom of the input.

todoDisplayModestringdefault: Product default

Control how the todo list is shown in the terminal UI.

logoAnimationstringdefault: once

Animate the droid logo on startup. Options: once, always, off.

themestringdefault: System theme

Color theme used by the TUI. Accepts a theme ID (see /themes).

overrideTerminalColorsbooleandefault: false

Force droid's theme to override the terminal's color scheme.

nerdFontbooleandefault: false

Enable Nerd Font glyphs in the UI (requires a Nerd Font in your terminal).

Additional sound and notification settings

Extends the Sound notifications section with toggles for the bell, per-event focus modes, and subagent activity.

Mission settings

Configure Missions, multi-agent orchestration runs.

missionModelSettings.workerModelstringdefault: Inherits

Default model used by mission worker subagents. Accepts any available model ID.

missionModelSettings.workerReasoningEffortstringdefault: Model default

Reasoning effort for mission workers. Options are model-dependent (see /models).

missionModelSettings.validationWorkerModelstringdefault: Inherits

Model used by mission validators (scrutiny / user-testing workers). Accepts any available model ID.

missionModelSettings.validationWorkerReasoningEffortstringdefault: Model default

Reasoning effort for validation workers. Options are model-dependent (see /models).

missionModelSettings.skipScrutinybooleandefault: false

Skip scrutiny validation milestones during missions.

missionModelSettings.skipUserTestingbooleandefault: false

Skip user-testing validation milestones during missions.

missionOrchestratorModelstringdefault: Inherits

Model used by the mission orchestrator. Accepts any available model ID.

missionOrchestratorReasoningEffortstringdefault: Model default

Reasoning effort for the mission orchestrator. Options are model-dependent (see /models).

keepSystemAwakeDuringMissionsbooleandefault: true

Prevent the OS from sleeping while a mission is running.

Subagent settings

Configure the autonomy and models used by subagents spawned by the Task tool. These appear in the Subagents tab of /settings.

Subagent autonomy level

subagentAutonomyLevel controls how much subagents can do without approval:

• inherit: Subagents use the parent session's autonomy level (default).
• off: Subagents require manual approval for every action.
• low, medium, high: Pre-authorize subagent work at or below that risk level.

An explicit level is still clamped to the org-managed maxAutonomyLevel, so it can never exceed the enterprise cap. Mission workers do not use this setting.

Subagent model settings

Subagents are routed by a complexity tier (light, medium, heavy). Each tier can pin its own model and reasoning effort under subagentModelSettings.

How the tiers are chosen:

• The built-in worker subagent runs at medium complexity and explorer at light. Custom droids and the Task tool can request a specific tier.
• inherit (the default) means the subagent uses the spawning session's active model and reasoning effort. Upgrading the parent session's model does not retroactively change a tier pinned to a specific model.
• A custom droid with an explicit model in its configuration uses that model directly and bypasses complexity routing.
• Without an explicit reasoning effort, a routed tier preserves the parent's active effort when it uses the same model; if it switches models, it uses the routed model's default. Explicit efforts are clamped to what the selected model supports.

Context and compaction

Controls when and how droid compacts the conversation to stay within the model's context window.

compactionTokenLimitnumberdefault: Model-dependent

Token threshold that triggers automatic compaction of the current session.

compactionTokenLimitPerModelobjectdefault: {}

Per-model overrides for compactionTokenLimit, as a { "<modelId>": number } map.

compactionModelstringdefault: same

Which model performs compaction: same uses the current session model, or specify a model ID.

modelFallbacksobjectdefault: {}

Per-model fallback routing when a selected model is unavailable, as a { "<modelId>": "<fallbackModelId>" } map.

Spec mode settings

Controls the persistent spec store created by Spec Mode.

Infrastructure

System-level settings for status line, worktrees, and request timeouts.

statusLineobjectdefault: unset

Custom status line configuration. Accepts { "command": string, "padding"?: number, "maxRows"?: number }. The command is executed and its stdout rendered above the input. Configure interactively with /statusline.

worktreeDirectorystringdefault: ~/.factory/worktrees

Default parent directory for git worktrees created with --worktree / -w.

llmRequestTimeoutnumberdefault: Product default

Timeout in milliseconds for individual LLM requests before they are aborted.

subagentInactivityTimeoutnumberdefault: Product default

Timeout in milliseconds for subagent inactivity before Droid treats the worker as stalled.

remoteAccessEnabledbooleandefault: false

Allow this machine to be used for remote Droid Computer access.

Enterprise and org-level settings

Factory App usage alert preferences

The following preference is stored in each user's Factory App profile. It cannot be configured in settings.json.

Example configuration

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