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

# Configure AI providers in your dotbot project

> Switch between Claude, Codex, Antigravity, Copilot, and OpenCode, set per-task model tiers, and verify provider CLIs are installed.

dotbot is a multi-provider AI development framework. Rather than committing to a single AI service, you can switch providers at any time by setting the `provider` field in `settings.default.json`, and you can mix providers across phases by setting analysis and execution models separately. Each provider ships with its own CLI adapter and stream parser, so the rest of the workflow engine stays unchanged regardless of which provider you choose.

## Supported providers

dotbot ships with five providers. Each one wraps a command-line tool and exposes its own permission modes that control how autonomous the AI is during execution.

| Provider      | Display name         | CLI executable | Permission modes (default first) |
| ------------- | -------------------- | -------------- | -------------------------------- |
| `claude`      | Claude (Anthropic)   | `claude`       | `bypassPermissions`, `auto`      |
| `codex`       | Codex (OpenAI)       | `codex`        | `bypass`, `full-auto`            |
| `antigravity` | Antigravity (Google) | `agy`          | `yolo`, `auto_edit`              |
| `copilot`     | GitHub Copilot CLI   | `copilot`      | `bypass`, `workspace`            |
| `opencode`    | OpenCode (SST)       | `opencode`     | `bypass`                         |

`claude` is the default provider. Each provider's full configuration lives in a JSON file under `content/settings/providers/` (for example, `content/settings/providers/claude.json`).

<Note>
  Antigravity (Google) replaces the former Gemini provider. Its executable is `agy`, and its default permission mode is `yolo`.
</Note>

## Permission modes

Permission modes map to provider-specific CLI flags. The first mode listed for each provider is its default.

| Provider    | Mode                | What it does                                                                                                                                 |
| ----------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude      | `bypassPermissions` | Skips all permission checks. Works on all plans and models.                                                                                  |
| Claude      | `auto`              | An AI classifier approves or blocks each action. Available on Max, Team, Enterprise, and API plans, not Pro. The fast tier is not supported. |
| Codex       | `bypass`            | Skips all approval and sandbox checks.                                                                                                       |
| Codex       | `full-auto`         | Workspace-scoped auto-approve, with on-request approval for risky operations.                                                                |
| Antigravity | `yolo`              | Auto-approves all tool calls without prompts.                                                                                                |
| Antigravity | `auto_edit`         | Uses Antigravity's default permission review flow.                                                                                           |
| Copilot     | `bypass`            | Allows all tools, paths, and URLs, disables prompts, and enables autonomous continuation.                                                    |
| Copilot     | `workspace`         | Allows local read, write, and shell tools across the workspace without granting all URLs.                                                    |
| OpenCode    | `bypass`            | Auto-approves permissions that are not explicitly denied.                                                                                    |

<Warning>
  The default mode for every provider skips confirmation prompts. Only run these modes in isolated environments where unreviewed file-system changes are acceptable.
</Warning>

## Switching providers

Set the `provider` field in `settings.default.json` to one of the five provider names. Leave `permission_mode` as `null` to use the provider's own default mode, or set it to a valid mode from the table above to override that default:

```json settings.default.json theme={null}
{
  "provider": "claude",
  "permission_mode": null
}
```

The change takes effect for the next task that starts. Running tasks are not interrupted.

## Model tiers

dotbot does not reference model names like Sonnet or Opus directly in your workflow. Instead, each provider exposes three capability tiers: `fast`, `balanced`, and `best`. Every provider defaults to `best`. The `providers` block in `settings.default.json` maps each tier to a concrete model for that provider:

```json settings.default.json theme={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"
      }
    }
  }
}
```

Each provider keeps its own tier mapping, so switching providers does not require touching any task that selects a tier. To target a different underlying model, edit the tier mapping for that provider rather than changing the tier name used by a task.

## Setting analysis and execution tiers

The `analysis.model` and `execution.model` fields set the baseline tier for every task that does not declare its own. Both default to `best`. Point them at different tiers to balance cost and quality across phases:

```json settings.default.json theme={null}
{
  "analysis": {
    "model": "best"
  },
  "execution": {
    "model": "best"
  }
}
```

The value is a tier name (`fast`, `balanced`, or `best`), not a model name. dotbot resolves the tier to a concrete model through the provider's `models` mapping at run time.

## Per-task tier overrides

An individual task in `workflow.json` can set a `model` field that overrides the baseline tier for that one task. Use a lighter tier for straightforward steps and reserve `best` for open-ended reasoning:

```json theme={null}
{
  "name": "Plan Task Groups",
  "type": "prompt",
  "workflow": "03a-plan-task-groups.md",
  "model": "balanced"
}
```

<Tip>
  Use `fast` or `balanced` for structured, well-scoped tasks, and reserve `best` for analysis and synthesis. Selecting a tier per task can reduce token spend on large pipelines without sacrificing quality where it matters.
</Tip>

## Tier resolution order

When dotbot resolves which model to use for a task, it evaluates these sources from highest to lowest priority:

1. The `model` tier on the individual task in `workflow.json`.
2. The `execution.model` (or `analysis.model`) tier in `settings.default.json`.
3. The provider's `default_model` (`best`).

The resolved tier is then mapped to a concrete model through the active provider's `models` block. The first non-null value in the chain wins.

## Verifying provider availability

Run `dotbot doctor` to check that a provider CLI is installed and on your `PATH`:

```powershell theme={null}
dotbot doctor
```

The check passes when at least one provider executable (`claude`, `codex`, `agy`, `opencode`, or `copilot`) is found. When you start a run, dotbot also verifies that the configured provider's executable is available and fails early with a clear message if it is missing.

<Note>
  dotbot delegates authentication to each provider's own CLI. Sign in with the provider's tool (for example, `claude` or `codex`) before starting a run, and confirm the CLI is on your `PATH` with `dotbot doctor`.
</Note>