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 live in two files that are deep-merged at startup, giving you team-wide defaults and per-machine overrides without conflict.

Settings files and merge order

Settings are resolved by merging two files in order. Later files win on any key that appears in both.

Step	File	Purpose
1	`.bot/settings/settings.default.json`	Team-wide defaults. Checked into version control. Edit this to change defaults for everyone on the project.
2	`.bot/.control/settings.json`	User-local overrides. Gitignored. Create or edit this file to override settings on your machine without affecting teammates.

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

instance_id

string | null

default:"null"

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

workflow

string

default:"default"

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

provider

string

default:"claude"

The AI provider to use. One of claude, codex, or gemini. Change this in the Settings tab or by editing .bot/.control/settings.json.

permission_mode

string | null

default:"null"

Override the provider’s default permission mode. Valid values depend on the provider:

claude: bypass, auto
codex: bypass, full-auto
gemini: yolo, auto-edit

When null, the provider’s configured default is used.

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

analysis.auto_approve_splits

boolean

default:"false"

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

analysis.split_threshold_effort

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.

analysis.question_timeout_hours

number | null

default:"null"

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

analysis.mode

string

default:"on-demand"

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

analysis.model

string

default:"Opus"

Model alias used for analysis. Can be overridden per-task. Aliases are resolved against the active provider’s model map (e.g. Opus → claude-opus-4-5 for Claude).

`execution` object

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

execution.model

string

default:"Opus"

Model alias used during task execution. Can be overridden per-task via the model field in task_create.

execution.max_concurrent

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.

`editor` object

Configures IDE integration launched after task commits.

editor.name

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.

editor.custom_command

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.

costs.hourly_rate

number

default:"50"

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

costs.ai_cost_per_task

number

default:"0.50"

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

costs.ai_speedup_factor

number

default:"10"

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

costs.currency

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.

operations.file_retry_count

integer

default:"3"

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

operations.file_retry_base_ms

integer

default:"50"

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

`logging` object

Controls log output verbosity and retention.

logging.console_level

string

default:"Info"

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

logging.file_level

string

default:"Debug"

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

logging.retention_days

integer

default:"7"

Number of days to retain log files before automatic deletion.

logging.max_file_size_mb

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.

mothership.enabled

boolean

default:"false"

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

mothership.server_url

string

default:"\"\""

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

mothership.api_key

string

default:"\"\""

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

mothership.channel

string

default:"teams"

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

mothership.recipients

array of strings

default:"[]"

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

mothership.project_name

string

default:"\"\""

Project display name used in notification messages.

mothership.project_description

string

default:"\"\""

Short project description included in notification context.

mothership.poll_interval_seconds

integer

default:"30"

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

mothership.sync_tasks

boolean

default:"true"

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

mothership.sync_questions

boolean

default:"true"

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

Full default settings file

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

{
  "instance_id": null,
  "workflow": "default",
  "provider": "claude",
  "permission_mode": null,
  "analysis": {
    "auto_approve_splits": false,
    "split_threshold_effort": "XL",
    "question_timeout_hours": null,
    "mode": "on-demand",
    "model": "Opus"
  },
  "execution": {
    "model": "Opus",
    "max_concurrent": 1
  },
  "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
  }
}

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

`analysis` object

`execution` object

`editor` object

`costs` object

`operations` object

`logging` object

`mothership` object

Full default settings file

CLI

MCP Tools

Architecture

​Settings files and merge order

​Root-level settings

​analysis object

​execution object

​editor object

​costs object

​operations object

​logging object

​mothership object

​Full default settings file

Settings files and merge order

Root-level settings

`analysis` object

`execution` object

`editor` object

`costs` object

`operations` object

`logging` object

`mothership` object

Full default settings file