dotbot settings.default.json reference guide

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.

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

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

Root-level settings

string | null

default:"null"

Unique identifier for this project instance. Auto-generated on first run if null. Used to correlate telemetry and mothership sync.

string

default:"start-from-prompt"

Name of the active workflow. Set automatically when you run dotbot init -Workflow <name>.

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.

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 for what each mode does.

`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.

string

default:"claude-haiku-4-5"

Model ID used when the fast tier is selected for the Claude provider.

string

default:"claude-sonnet-4-6"

Model ID used when the balanced tier is selected for the Claude provider.

string

default:"claude-opus-4-7"

Model ID used when the best tier is selected for the Claude provider.

string

default:"gpt-5.4-mini"

Model ID used when the fast tier is selected for the Codex provider.

string

default:"gpt-5.4"

Model ID used when the balanced tier is selected for the Codex provider.

string

default:"gpt-5.5"

Model ID used when the best tier is selected for the Codex provider.

string

default:"gemini-3.5-flash"

Model ID used when the fast tier is selected for the Antigravity provider.

string

default:"gemini-3.5-flash"

Model ID used when the balanced tier is selected for the Antigravity provider.

string

default:"gemini-3.5-flash"

Model ID used when the best tier is selected for the Antigravity provider.

string

default:"opencode-go/deepseek-v4-flash"

Model ID used when the fast tier is selected for the OpenCode provider.

string

default:"opencode-go/deepseek-v4-pro"

Model ID used when the balanced tier is selected for the OpenCode provider.

string

default:"opencode-go/kimi-k2.6"

Model ID used when the best tier is selected for the OpenCode provider.

string

default:"auto"

Model selection for the Copilot provider’s fast tier. auto lets Copilot choose the fastest suitable available model.

string

default:"auto"

Model selection for the Copilot provider’s balanced tier. auto lets Copilot balance speed, cost, and capability.

string

default:"auto"

Model selection for the Copilot provider’s best tier. auto lets Copilot choose the best available model for the task.

`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.

boolean

default:"false"

When true, task-split proposals generated by the analysis phase are automatically approved without human review.

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.

number | null

default:"null"

Hours before an unanswered analysis-phase question is automatically skipped. null means no timeout.

string

default:"on-demand"

Analysis scheduling mode. on-demand runs analysis only when a task reaches the front of the queue.

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.

`execution` object

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

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.

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.

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.

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.

`editor` object

Configures IDE integration launched after task commits.

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.

string

default:"\"\""

Custom shell command to invoke when editor.name is set to custom.

`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.

number

default:"50"

Developer hourly rate in the configured currency. Used to calculate estimated human time cost.

number

default:"0.50"

Average AI token cost per completed task (in the configured currency). Used for cost projection.

number

default:"10"

Multiplier representing how much faster AI completes a task compared to a human. Used in time-savings calculations.

string

default:"USD"

ISO 4217 currency code for cost display (e.g. USD, EUR, GBP).

`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.

integer

default:"3"

Number of retry attempts for file operations that fail due to transient lock contention.

integer

default:"50"

Base delay in milliseconds between file retry attempts. Actual delay uses exponential backoff.

`logging` object

Controls log output verbosity and retention.

string

default:"Info"

Minimum log level written to the terminal. One of Debug, Info, Warning, Error.

string

default:"Debug"

Minimum log level written to log files in .bot/.control/logs/.

integer

default:"7"

Number of days to retain log files before automatic deletion.

integer

default:"50"

Maximum size in megabytes for a single log file before it is rotated.

`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.

boolean

default:"false"

When true, dotbot pushes task updates, questions, and status to the configured server.

string

default:"\"\""

Base URL of the mothership server (e.g. https://dotbot.example.com).

string

default:"\"\""

API key for authenticating with the mothership server. Store this in .bot/.control/settings.json, not in the tracked settings file.

string

default:"teams"

Notification channel for human-in-the-loop questions. One of teams, email, jira.

array of strings

default:"[]"

List of recipient addresses or IDs for notifications (emails, Teams UPNs, Jira user IDs).

string

default:"\"\""

Project display name used in notification messages.

string

default:"\"\""

Short project description included in notification context.

integer

default:"30"

How often (in seconds) dotbot polls the mothership server for answers to pending questions.

boolean

default:"true"

When true, task state changes are synced to the mothership server.

boolean

default:"true"

When true, pending questions are pushed to the mothership and answers are pulled via polling.

`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.

boolean

default:"false"

When true, the runtime connects to the control plane and sends periodic heartbeats.

string

default:"\"\""

Base URL of the control plane server.

string

default:"\"\""

API key for authenticating with the control plane. Store this in .bot/.control/settings.json.

integer

default:"5"

How often (in seconds) the runtime sends a heartbeat to the control plane.

`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.

boolean

default:"false"

When true, dotbot watches the configured folders for file events.

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.

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.

{
  "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"
      }
    ]
  }
}

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

CLI

MCP Tools

Architecture

dotbot settings.default.json reference guide

Settings files and merge order

Root-level settings

`providers` object

`analysis` object

`execution` object

`editor` object

`costs` object

`operations` object

`logging` object

`mothership` object

`control_plane` object

`file_listener` object

Full default settings file

​Settings files and merge order

​Root-level settings

​providers object

​analysis object

​execution object

​editor object

​costs object

​operations object

​logging object

​mothership object

​control_plane object

​file_listener object

​Full default settings file

Settings files and merge order

Root-level settings

`providers` object

`analysis` object

`execution` object

`editor` object

`costs` object

`operations` object

`logging` object

`mothership` object

`control_plane` object

`file_listener` object

Full default settings file