Configure Atomic

After your first session, save global preferences in ~/.atomic/agent/settings.json. Use .atomic/settings.json for overrides that apply only to the current project.

Example

Choose the provider and model you have configured, then add the settings you need:

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "compression_ratio": 0.5,
    "preserve_recent": 2
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3
  },
  "httpIdleTimeoutMs": 300000,
  "enabledModels": ["claude-*", "gpt-4o"],
  "warnings": {
    "anthropicExtraUsage": true
  },
  "packages": ["pi-skills"],
  "workflows": ["./workflows/*.ts"]
}

Project overrides

Project settings override global settings:

Nested objects merge recursively. You can change one field without repeating its siblings.
Arrays and scalar values replace the global value.

This example changes only the compaction token reserve:

// ~/.atomic/agent/settings.json (global)
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 16384 }
}

// .atomic/settings.json (project)
{
  "compaction": { "reserveTokens": 8192 }
}

// Result
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 8192 }
}

Next step

Every field is listed in the Settings reference.