> ## Documentation Index
> Fetch the complete documentation index at: https://docs.factory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings

> Configure how droid behaves and integrates with your workflow.

## 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

| OS            | Location                               |
| ------------- | -------------------------------------- |
| 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**.

### 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](/cli/configuration/agents-md) for repository instructions, conventions, and validation commands.
* Use [MCP servers](/cli/configuration/mcp), [hooks](/cli/configuration/hooks-guide), and [skills](/cli/configuration/skills) for integrations, automation, and reusable workflows.

## Available settings

| 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.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.                                            |
| `diffMode`                               | `github`, `unified`                                                        | `github`                      | Choose between split GitHub-style diffs and a single-column view.              |
| `completionSound`                        | `off`, `bell`, `fx-ok01`, `fx-ack01`, or custom file path                  | `fx-ok01`                     | Audio cue when a response finishes.                                            |
| `awaitingInputSound`                     | `off`, `bell`, `fx-ok01`, `fx-ack01`, or custom file path                  | `fx-ack01`                    | Audio cue when droid is waiting for user input.                                |
| `soundFocusMode`                         | `always`, `focused`, `unfocused`                                           | `always`                      | When to play sound notifications.                                              |
| `commandAllowlist`                       | Array of commands                                                          | Safe defaults provided        | Commands that run without extra confirmation.                                  |
| `commandDenylist`                        | Array of commands                                                          | Restrictive defaults provided | Commands that always require confirmation.                                     |
| `includeCoAuthoredByDroid`               | `true`, `false`                                                            | `true`                        | Automatically append the Droid co-author trailer to commits.                   |
| `enableDroidShield`                      | `true`, `false`                                                            | `true`                        | Enable secret scanning and git guardrails.                                     |
| `hooksDisabled`                          | `true`, `false`                                                            | `false`                       | Globally disable all hooks execution.                                          |
| `ideAutoConnect`                         | `true`, `false`                                                            | `false`                       | Auto-connect to IDE from external terminals.                                   |
| `showThinkingInMainView`                 | `true`, `false`                                                            | `false`                       | Display AI thinking/reasoning blocks in the main chat view.                    |
| `customModels`                           | Array of model configs                                                     | `[]`                          | Custom model configurations for BYOK. See [BYOK docs](/cli/byok/overview).     |

### Model

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

### 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

Use `sessionDefaultSettings.interactionMode` to choose whether new sessions start in Auto or Spec Mode, and `sessionDefaultSettings.autonomyLevel` to set the default [Autonomy Level](/cli/user-guides/auto-run). `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

<Note>Access sound settings via `/settings` or `Shift+Tab` → **Settings** in the TUI.</Note>

### 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

## 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

```json theme={null}
{
  "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

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

***

### Need more?

* [CLI Overview](/cli/getting-started/overview) – see the main TUI workflow
* [CLI Reference](/reference/cli-reference) – command flags & options
* [IDE Integrations](/integrations/ide-integrations) – editor-specific setup
* [Custom models & BYOK](/cli/byok/overview) - add custom models and API keys