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

# dotbot settings.default.json reference guide

> Complete reference for dotbot settings files and merge order - provider selection, model defaults, concurrency limits, logging, cost tracking, and sync.

dotbot settings control how the framework behaves at runtime: which AI provider to use, how many tasks run concurrently, logging verbosity, cost tracking, and whether to push telemetry to a central server. Settings are resolved by deep-merging four layers at startup, so framework defaults, project defaults, user preferences, and per-machine overrides all compose without conflict.

***

## Settings files and merge order

Settings are resolved from four layers, merged in order from lowest to highest precedence. Later layers win on any key that appears in multiple layers.

| Layer | File                                                                                         | Purpose                                                                                                                                                       |
| ----- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1     | `<DOTBOT_HOME>/content/settings/settings.default.json`                                       | Framework defaults. Shipped with dotbot. Never edit this file directly.                                                                                       |
| 2     | `.bot/content/settings/settings.default.json`                                                | Optional project-tracked override of framework defaults. Check this file into version control when you want to establish project-wide defaults for your team. |
| 3     | `~/.config/dotbot/settings.json` (macOS/Linux) or `%APPDATA%\dotbot\settings.json` (Windows) | User-level overrides. Apply across all projects on the current machine. Not checked into version control.                                                     |
| 4     | `.bot/.control/settings.json`                                                                | Per-machine project overrides. Gitignored. The Settings tab in the dashboard writes here.                                                                     |

<Warning>
  The `.bot/.control/` directory is always gitignored. Never commit files from that directory - it contains machine-local state, session locks, and API keys.
</Warning>

<Note>
  The Settings tab in the web dashboard writes to `.bot/.control/settings.json`, so any change made in the UI is automatically local-only.
</Note>

***

## Root-level settings

<ParamField path="instance_id" type="string | null" default="null">
  Unique identifier for this project instance. Auto-generated on first run if `null`. Used to correlate telemetry and mothership sync.
</ParamField>

<ParamField path="workflow" type="string" default="start-from-prompt">
  Name of the active workflow. Set automatically when you run `dotbot init -Workflow <name>`.
</ParamField>

<ParamField path="provider" type="string" default="claude">
  The AI provider to use. One of `claude`, `codex`, `antigravity`, `copilot`, or `opencode`. Change this in the Settings tab or by editing `.bot/.control/settings.json`.
</ParamField>

<ParamField path="permission_mode" type="string | null" default="null">
  Override the provider's default permission mode. Valid values depend on the active provider:

  * **claude**: `bypassPermissions`, `auto`
  * **codex**: `bypass`, `full-auto`
  * **antigravity**: `yolo`, `auto_edit`
  * **copilot**: `bypass`, `workspace`
  * **opencode**: `bypass`

  When `null`, the provider's configured default is used. See the [Providers](/reference/providers) reference for what each mode does.
</ParamField>

***

## `providers` object

Overrides the concrete model IDs resolved for each provider's fast, balanced, and best tiers. Values here take precedence over the provider's own defaults. You can update a single tier without touching the others.

<ParamField path="providers.claude.models.fast" type="string" default="claude-haiku-4-5">
  Model ID used when the `fast` tier is selected for the Claude provider.
</ParamField>

<ParamField path="providers.claude.models.balanced" type="string" default="claude-sonnet-4-6">
  Model ID used when the `balanced` tier is selected for the Claude provider.
</ParamField>

<ParamField path="providers.claude.models.best" type="string" default="claude-opus-4-7">
  Model ID used when the `best` tier is selected for the Claude provider.
</ParamField>

<ParamField path="providers.codex.models.fast" type="string" default="gpt-5.4-mini">
  Model ID used when the `fast` tier is selected for the Codex provider.
</ParamField>

<ParamField path="providers.codex.models.balanced" type="string" default="gpt-5.4">
  Model ID used when the `balanced` tier is selected for the Codex provider.
</ParamField>

<ParamField path="providers.codex.models.best" type="string" default="gpt-5.5">
  Model ID used when the `best` tier is selected for the Codex provider.
</ParamField>

<ParamField path="providers.antigravity.models.fast" type="string" default="gemini-3.5-flash">
  Model ID used when the `fast` tier is selected for the Antigravity provider.
</ParamField>

<ParamField path="providers.antigravity.models.balanced" type="string" default="gemini-3.5-flash">
  Model ID used when the `balanced` tier is selected for the Antigravity provider.
</ParamField>

<ParamField path="providers.antigravity.models.best" type="string" default="gemini-3.5-flash">
  Model ID used when the `best` tier is selected for the Antigravity provider.
</ParamField>

<ParamField path="providers.opencode.models.fast" type="string" default="opencode-go/deepseek-v4-flash">
  Model ID used when the `fast` tier is selected for the OpenCode provider.
</ParamField>

<ParamField path="providers.opencode.models.balanced" type="string" default="opencode-go/deepseek-v4-pro">
  Model ID used when the `balanced` tier is selected for the OpenCode provider.
</ParamField>

<ParamField path="providers.opencode.models.best" type="string" default="opencode-go/kimi-k2.6">
  Model ID used when the `best` tier is selected for the OpenCode provider.
</ParamField>

<ParamField path="providers.copilot.models.fast" type="string" default="auto">
  Model selection for the Copilot provider's fast tier. `auto` lets Copilot choose the fastest suitable available model.
</ParamField>

<ParamField path="providers.copilot.models.balanced" type="string" default="auto">
  Model selection for the Copilot provider's balanced tier. `auto` lets Copilot balance speed, cost, and capability.
</ParamField>

<ParamField path="providers.copilot.models.best" type="string" default="auto">
  Model selection for the Copilot provider's best tier. `auto` lets Copilot choose the best available model for the task.
</ParamField>

***

## `analysis` object

Controls the pre-flight analysis phase that runs before each AI task. The analysis phase reads the task, explores the codebase, resolves questions, and produces a context package consumed by the implementation phase.

<ParamField path="analysis.auto_approve_splits" type="boolean" default="false">
  When `true`, task-split proposals generated by the analysis phase are automatically approved without human review.
</ParamField>

<ParamField path="analysis.split_threshold_effort" type="string" default="XL">
  Effort size at which the analysis phase proposes splitting a task. One of `XS`, `S`, `M`, `L`, `XL`. Tasks estimated at or above this effort trigger a split proposal.
</ParamField>

<ParamField path="analysis.question_timeout_hours" type="number | null" default="null">
  Hours before an unanswered analysis-phase question is automatically skipped. `null` means no timeout.
</ParamField>

<ParamField path="analysis.mode" type="string" default="on-demand">
  Analysis scheduling mode. `on-demand` runs analysis only when a task reaches the front of the queue.
</ParamField>

<ParamField path="analysis.model" type="string" default="best">
  Model tier used for analysis. One of `fast`, `balanced`, or `best`. The tier is resolved to a concrete model ID using the active provider's model map in the `providers` block.
</ParamField>

***

## `execution` object

Controls the implementation (execution) phase - the phase where the AI agent carries out the work described in a task.

<ParamField path="execution.model" type="string" default="best">
  Model tier used during task execution. One of `fast`, `balanced`, or `best`. Can be overridden per-task via the `model` field in `task_create`.
</ParamField>

<ParamField path="execution.max_concurrent" type="integer" default="1">
  Maximum number of tasks that run in parallel within a single workflow. Increase this to shorten wall-clock time when tasks are independent. Each concurrent task runs in its own git worktree.
</ParamField>

<ParamField path="execution.provider_completion_grace_seconds" type="integer" default="10">
  Seconds to wait after a provider process signals completion before the runtime treats the session as fully closed. Allows the provider to flush any final output before the harness collects it.
</ParamField>

<ParamField path="execution.provider_stop_check_interval_seconds" type="integer" default="2">
  How often (in seconds) the runtime polls the provider process to check whether it has stopped cleanly during the graceful-completion window.
</ParamField>

***

## `editor` object

Configures IDE integration launched after task commits.

<ParamField path="editor.name" type="string" default="off">
  IDE to open after a task completes. `off` disables IDE integration. Other values (e.g. `cursor`, `vscode`) map to known IDE launch commands.
</ParamField>

<ParamField path="editor.custom_command" type="string" default="&#x22;&#x22;">
  Custom shell command to invoke when `editor.name` is set to `custom`.
</ParamField>

***

## `costs` object

Parameters used to estimate time-savings and AI spend in the dashboard's cost report. These settings affect display only - they do not change runtime behaviour.

<ParamField path="costs.hourly_rate" type="number" default="50">
  Developer hourly rate in the configured currency. Used to calculate estimated human time cost.
</ParamField>

<ParamField path="costs.ai_cost_per_task" type="number" default="0.50">
  Average AI token cost per completed task (in the configured currency). Used for cost projection.
</ParamField>

<ParamField path="costs.ai_speedup_factor" type="number" default="10">
  Multiplier representing how much faster AI completes a task compared to a human. Used in time-savings calculations.
</ParamField>

<ParamField path="costs.currency" type="string" default="USD">
  ISO 4217 currency code for cost display (e.g. `USD`, `EUR`, `GBP`).
</ParamField>

***

## `operations` object

Low-level runtime behaviour for file I/O. These settings rarely need adjustment unless you are running dotbot on a filesystem with high lock contention.

<ParamField path="operations.file_retry_count" type="integer" default="3">
  Number of retry attempts for file operations that fail due to transient lock contention.
</ParamField>

<ParamField path="operations.file_retry_base_ms" type="integer" default="50">
  Base delay in milliseconds between file retry attempts. Actual delay uses exponential backoff.
</ParamField>

***

## `logging` object

Controls log output verbosity and retention.

<ParamField path="logging.console_level" type="string" default="Info">
  Minimum log level written to the terminal. One of `Debug`, `Info`, `Warning`, `Error`.
</ParamField>

<ParamField path="logging.file_level" type="string" default="Debug">
  Minimum log level written to log files in `.bot/.control/logs/`.
</ParamField>

<ParamField path="logging.retention_days" type="integer" default="7">
  Number of days to retain log files before automatic deletion.
</ParamField>

<ParamField path="logging.max_file_size_mb" type="integer" default="50">
  Maximum size in megabytes for a single log file before it is rotated.
</ParamField>

***

## `mothership` object

Configures the central notification and sync server. This is an optional enterprise feature that lets dotbot push task updates and pending questions to a shared server, and receive answers via polling - enabling human-in-the-loop workflows across distributed teams.

<ParamField path="mothership.enabled" type="boolean" default="false">
  When `true`, dotbot pushes task updates, questions, and status to the configured server.
</ParamField>

<ParamField path="mothership.server_url" type="string" default="&#x22;&#x22;">
  Base URL of the mothership server (e.g. `https://dotbot.example.com`).
</ParamField>

<ParamField path="mothership.api_key" type="string" default="&#x22;&#x22;">
  API key for authenticating with the mothership server. Store this in `.bot/.control/settings.json`, not in the tracked settings file.
</ParamField>

<ParamField path="mothership.channel" type="string" default="teams">
  Notification channel for human-in-the-loop questions. One of `teams`, `email`, `jira`.
</ParamField>

<ParamField path="mothership.recipients" type="array of strings" default="[]">
  List of recipient addresses or IDs for notifications (emails, Teams UPNs, Jira user IDs).
</ParamField>

<ParamField path="mothership.project_name" type="string" default="&#x22;&#x22;">
  Project display name used in notification messages.
</ParamField>

<ParamField path="mothership.project_description" type="string" default="&#x22;&#x22;">
  Short project description included in notification context.
</ParamField>

<ParamField path="mothership.poll_interval_seconds" type="integer" default="30">
  How often (in seconds) dotbot polls the mothership server for answers to pending questions.
</ParamField>

<ParamField path="mothership.sync_tasks" type="boolean" default="true">
  When `true`, task state changes are synced to the mothership server.
</ParamField>

<ParamField path="mothership.sync_questions" type="boolean" default="true">
  When `true`, pending questions are pushed to the mothership and answers are pulled via polling.
</ParamField>

***

## `control_plane` object

Configures an optional central control plane that the runtime reports to via heartbeat. This is an enterprise feature for centrally monitoring and orchestrating multiple dotbot instances.

<ParamField path="control_plane.enabled" type="boolean" default="false">
  When `true`, the runtime connects to the control plane and sends periodic heartbeats.
</ParamField>

<ParamField path="control_plane.url" type="string" default="&#x22;&#x22;">
  Base URL of the control plane server.
</ParamField>

<ParamField path="control_plane.api_key" type="string" default="&#x22;&#x22;">
  API key for authenticating with the control plane. Store this in `.bot/.control/settings.json`.
</ParamField>

<ParamField path="control_plane.heartbeat_seconds" type="integer" default="5">
  How often (in seconds) the runtime sends a heartbeat to the control plane.
</ParamField>

***

## `file_listener` object

Configures filesystem watchers that trigger dotbot actions when files are created or changed in watched folders. This lets dotbot react to external events - for example, starting a task when a new briefing document lands in a product folder.

<ParamField path="file_listener.enabled" type="boolean" default="false">
  When `true`, dotbot watches the configured folders for file events.
</ParamField>

<ParamField path="file_listener.watchers" type="array of objects" default="[]">
  List of watcher configurations. Each watcher object has:

  * **folder** (`string`) - Path relative to the project root to watch.
  * **filter** (`string`) - Filename glob pattern. Use `*` to match all files.
  * **events** (`array of strings`) - File system events to watch for. Supported value: `created`.
  * **description** (`string`) - Human-readable label for this watcher, used in logs.
</ParamField>

***

## Full default settings file

This is the complete `settings.default.json` as shipped with dotbot. Copy this as a starting point and override only the values you need.

```json theme={null}
{
  "instance_id": null,
  "workflow": "start-from-prompt",
  "provider": "claude",
  "permission_mode": null,
  "providers": {
    "claude": {
      "models": {
        "fast": "claude-haiku-4-5",
        "balanced": "claude-sonnet-4-6",
        "best": "claude-opus-4-7"
      }
    },
    "codex": {
      "models": {
        "fast": "gpt-5.4-mini",
        "balanced": "gpt-5.4",
        "best": "gpt-5.5"
      }
    },
    "antigravity": {
      "models": {
        "fast": "gemini-3.5-flash",
        "balanced": "gemini-3.5-flash",
        "best": "gemini-3.5-flash"
      }
    },
    "opencode": {
      "models": {
        "fast": "opencode-go/deepseek-v4-flash",
        "balanced": "opencode-go/deepseek-v4-pro",
        "best": "opencode-go/kimi-k2.6"
      }
    },
    "copilot": {
      "models": {
        "fast": "auto",
        "balanced": "auto",
        "best": "auto"
      }
    }
  },
  "analysis": {
    "auto_approve_splits": false,
    "split_threshold_effort": "XL",
    "question_timeout_hours": null,
    "mode": "on-demand",
    "model": "best"
  },
  "execution": {
    "model": "best",
    "max_concurrent": 1,
    "provider_completion_grace_seconds": 10,
    "provider_stop_check_interval_seconds": 2
  },
  "editor": {
    "name": "off",
    "custom_command": ""
  },
  "costs": {
    "hourly_rate": 50,
    "ai_cost_per_task": 0.50,
    "ai_speedup_factor": 10,
    "currency": "USD"
  },
  "operations": {
    "file_retry_count": 3,
    "file_retry_base_ms": 50
  },
  "logging": {
    "console_level": "Info",
    "file_level": "Debug",
    "retention_days": 7,
    "max_file_size_mb": 50
  },
  "mothership": {
    "enabled": false,
    "server_url": "",
    "api_key": "",
    "channel": "teams",
    "recipients": [],
    "project_name": "",
    "project_description": "",
    "poll_interval_seconds": 30,
    "sync_tasks": true,
    "sync_questions": true
  },
  "control_plane": {
    "enabled": false,
    "url": "",
    "api_key": "",
    "heartbeat_seconds": 5
  },
  "file_listener": {
    "enabled": false,
    "watchers": [
      {
        "folder": "product/briefing",
        "filter": "*",
        "events": ["created"],
        "description": "New document in product briefing"
      }
    ]
  }
}
```

<Tip>
  Run `dotbot doctor` to validate your merged settings and confirm that the active provider is correctly configured before starting a workflow.
</Tip>