Settings

Configure the Atomic CLI via .atomic/settings.json.

Atomic’s configuration lives in settings.json. Two locations are supported, resolved in this order:

1. Project-local — .atomic/settings.json in the current repo.
2. Global — ~/.atomic/settings.json in your home directory.

Local entries override global ones for providers and workflows.

Example

{
  "$schema": "https://raw.githubusercontent.com/flora131/atomic/main/assets/settings.schema.json",
  "version": 1,
  "scm": "github",
  "providers": {
    "claude": {
      "chatFlags": ["--model", "claude-sonnet-4-6"],
      "envVars": { "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "16384" }
    }
  },
  "workflows": {
    "pr-review": {
      "command": "bunx",
      "args": ["./.atomic/workflows/pr-review/index.ts"],
      "agents": ["claude"]
    }
  }
}

Top-level fields

$schema · string

JSON Schema URL for editor autocomplete. Set to https://raw.githubusercontent.com/flora131/atomic/main/assets/settings.schema.json.

version · number

Config schema version. Currently 1.

scm · "github" | "azure-devops" | "sapling"

Source control provider. On every atomic chat / atomic workflow startup, Atomic reconciles the GitHub and Azure DevOps MCP servers across agent configs — .claude/settings.json (disabledMcpjsonServers), .opencode/opencode.json (mcp.<server>.enabled), and --disable-mcp-server <name> on Copilot CLI. sapling disables both servers everywhere. These servers are disabled by default to avoid consuming tokens on projects that don’t need them.

providers · object

Per-provider overrides keyed by claude, opencode, or copilot. Each value supports:

• chatFlags — string[]. Replaces the provider’s default chat flags entirely when set.
• envVars — Record<string, string>. Merged on top of provider defaults; user values win on conflict.

workflows · object

Custom workflow registry. Each key is the alias the atomic CLI exposes; each value points at an external entry that calls hostLocalWorkflows([wf]). See registering workflows.

Each entry supports:

• command — string (required). Executable to spawn (e.g. bunx, node, an absolute path).
• args — string[]. Static arguments prepended before Atomic’s hidden subcommands. Defaults to [].
• agents — ("claude" | "opencode" | "copilot")[] (required). Atomic registers one entry per agent listed.

Local entries override global ones with the same alias. Run atomic workflow refresh after editing.

providers example

Override Claude Code’s model and max output tokens for this project only:

{
  "providers": {
    "claude": {
      "chatFlags": ["--model", "claude-sonnet-4-6"],
      "envVars": { "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "16384" }
    }
  }
}

chatFlags is a full replacement — set it only if you need to replace defaults wholesale. envVars is merged, so you can add one variable without touching the rest.

Model selection and reasoning effort are managed by each underlying agent CLI (e.g. Claude Code’s /model), not Atomic. Atomic’s chat command spawns the agent’s native TUI — use the agent’s own controls when interactive.

Refreshing custom workflows

After editing the workflows map or any registered workflow file:

atomic workflow refresh

This re-spawns the metadata loader for every entry and reports loaded + broken entries with field-by-field diagnostics. Inside an atomic chat session it auto-defaults to JSON. See registering workflows for diagnostics.

CLI helper

For simple fields you can use atomic config set:

atomic config set scm github
atomic config set telemetry false