# AI Configuration

The `ai` section of the `atmos.yaml` configures the built-in AI assistant, including providers,
skills, tool execution, sessions, and project instructions.

> ⚠️ Experimental

## Quick Start

**File:** `atmos.yaml`

```yaml
ai:
  enabled: true
  default_provider: "anthropic"
  providers:
    anthropic:
      model: "claude-sonnet-4-6"
      api_key: !env "ANTHROPIC_API_KEY"
      max_tokens: 4096
```

```shell
export ANTHROPIC_API_KEY="your-api-key-here"
atmos ai chat
```

### CLI Provider Quick Start (No API Key)

CLI providers invoke your locally installed AI tool as a subprocess — no API key needed:

**File:** `atmos.yaml`

```yaml
ai:
  enabled: true
  default_provider: "claude-code"  # or "codex-cli", "copilot-cli", "opencode", "gemini-cli"
  providers:
    claude-code:
      max_turns: 10
```

```shell
brew install --cask claude-code && claude auth login
atmos ai chat
```

CLI-specific provider settings: `binary`, `max_turns`, `max_budget_usd`, `full_auto`, `allowed_tools`. See [Providers](/cli/configuration/ai/providers) for details.

## Configuration Reference

### Top-Level Structure

**File:** `atmos.yaml`

```yaml
ai:
  enabled: true                         # Enable AI features
  default_provider: "anthropic"         # Default provider for CLI commands
  default_skill: "general"              # Default AI skill

  # Provider connections
  providers:
    <provider-name>:
      model: "model-id"
      api_key: !env "ENV_VAR_NAME"
      max_tokens: 4096
      base_url: ""                      # Custom endpoint (optional)

  # Tool execution
  tools:
    enabled: true
    mode: require_confirmation   # require_confirmation | allow | yolo
    allowed: []
    restricted: []
    blocked: []

  # Session persistence
  sessions:
    enabled: true
    path: ".atmos/sessions"
    max_sessions: 10

  # Project instructions
  instructions:
    enabled: true
    file: "ATMOS.md"

  # Automatic context discovery
  context:
    enabled: true
    auto_include: ["stacks/**/*.yaml"]
    exclude: ["**/node_modules/**"]
    max_files: 100
    max_size_mb: 10

  # Web search
  web_search:
    enabled: false

  # Custom skills
  skills:
    <skill-name>:
      display_name: "Display Name"
      description: "What this skill does"
      system_prompt: "..."
      allowed_tools: []
```

### Global Settings

- **`enabled`** — Enable or disable AI features (default: `false`)
- **`default_provider`** — Default AI provider. **API providers:** `anthropic`, `openai`, `gemini`, `github`, `grok`, `openrouter`, `deepseek`, `zai`, `ollama`, `bedrock`, `azureopenai`. **CLI providers:** `claude-code`, `codex-cli`, `copilot-cli`, `opencode`, `gemini-cli`. Leave unset, or set to `auto`, to auto-detect an installed CLI provider on `PATH` (falls back to `anthropic`).
- **`default_skill`** — Default skill to activate (default: `general`)
- **`send_context`** — Automatically send stack configurations to AI for context-aware answers (default: `false`)
- **`prompt_on_send`** — Prompt user before sending context, even when `send_context` is `true` (default: `true`)
- **`max_history_messages`** — Maximum conversation messages to keep. Simple message-based limit (default: `0` = unlimited)
- **`max_history_tokens`** — Maximum tokens in conversation history. More precise, approximate counting (~10-20% accuracy). If both limits are set, whichever is hit first wins (default: `0` = unlimited)
- **`timeout_seconds`** — Request timeout in seconds (default: `60`). For the `claude-code` provider this counts the AI's working time. Time spent waiting for you at a tool approval prompt does not count.
- **`max_tool_iterations`** — Maximum number of tool execution loops per AI request. Increase for complex queries that require many tool calls (e.g., IAM audit across multiple regions). Default: `25`
- **`max_context_files`** — Maximum stack files to send for context (default: `10`)
- **`max_context_lines`** — Maximum lines per file when sending context (default: `500`)

### Provider Settings

Each provider in the `providers` map supports:

- **`model`** — Model identifier (defaults vary by provider)
- **`api_key`** — API key for the provider. Use `!env` to read from an environment variable (e.g., `api_key: !env "ANTHROPIC_API_KEY"`).
- **`max_tokens`** — Maximum tokens per response. Roughly 1000 tokens = 750 words.
- **`base_url`** — Custom API endpoint (required for Grok, Azure OpenAI; AWS region for Bedrock)
- **`timeout_seconds`** — Per-provider request timeout override

## Multi-Provider Configuration

Atmos supports both API and CLI providers. Configure multiple and switch between them with **Ctrl+P** in the TUI, or set `default_provider` for CLI commands.

**File:** `atmos.yaml`

```yaml
ai:
  enabled: true
  default_provider: "anthropic"

  providers:
    # Cloud Providers
    anthropic:
      model: "claude-sonnet-4-6"
      api_key: !env "ANTHROPIC_API_KEY"
      max_tokens: 4096

    openai:
      model: "gpt-5.4"
      api_key: !env "OPENAI_API_KEY"
      max_tokens: 4096

    gemini:
      model: "gemini-3.8-flash"
      api_key: !env "GEMINI_API_KEY"
      max_tokens: 8192

    grok:
      model: "grok-4-latest"
      api_key: !env "XAI_API_KEY"
      max_tokens: 4096
      base_url: "https://api.x.ai/v1"

    # Local Provider (no API key needed)
    ollama:
      model: "llama4"
      base_url: "http://localhost:11434/v1"

    # Enterprise Providers
    bedrock:
      model: "anthropic.claude-sonnet-4-6"
      base_url: "us-east-1"              # AWS region

    azureopenai:
      model: "gpt-4o"                    # Your Azure deployment name
      api_key: !env "AZURE_OPENAI_API_KEY"
      base_url: "https://your-resource.openai.azure.com"
      api_version: "2025-04-01-preview"
```

## Conversation History Management

By default, Atmos sends full conversation history with each request. For long conversations, this can cause
rate limiting and higher costs. Three approaches to manage it:

- ****Simple truncation** — `max_history_messages: 20`** — Most users, easy to configure.
- ****Auto-compact** — `sessions.auto_compact.enabled: true`** — Long conversations, preserves context.
- ****Both** — Truncation + auto-compact** — Maximum control, safety net.

Auto-compact summarizes old messages using AI instead of dropping them, preserving important context.
See [Sessions](/cli/configuration/ai/sessions) for details.

:::warning
Setting history too low (4-6 messages) causes the AI to lose important context. Start with 20-30.
:::

## Environment Variables

```shell
# API Keys (alternative to api_key with !env in config)
export ATMOS_ANTHROPIC_API_KEY="your-key"
export ATMOS_OPENAI_API_KEY="your-key"
export ATMOS_GEMINI_API_KEY="your-key"
export ATMOS_XAI_API_KEY="your-key"

# Context Control
export ATMOS_AI_SEND_CONTEXT=true
```

## Verify Configuration

```shell
atmos ai ask "Hello, are you working?"
```

## Context Discovery

The `context` section controls automatic file discovery for AI context:

- **`context.enabled`** — Enable automatic context loading (default: `true`)
- **`context.auto_include`** — Glob patterns for files to automatically include (e.g., `["stacks/**/*.yaml"]`)
- **`context.exclude`** — Glob patterns to exclude from context (e.g., `["**/node_modules/**"]`)
- **`context.max_files`** — Maximum files to include (default: `100`)
- **`context.max_size_mb`** — Maximum total size in MB (default: `10`)
- **`context.follow_gitignore`** — Respect `.gitignore` patterns (default: `true`)
- **`context.show_files`** — Show included files in UI output (default: `false`)
- **`context.cache_enabled`** — Cache discovered files for faster subsequent requests (default: `true`)
- **`context.cache_ttl`** — Cache time-to-live in seconds (default: `300`)

## Web Search

The `web_search` section enables the AI to search the web for documentation and solutions:

- **`web_search.enabled`** — Enable web search tool (default: `false`)
- **`web_search.max_results`** — Maximum search results to return (default: `10`)
- **`web_search.google_api_key`** — Google Custom Search API key (for Google Custom Search)
- **`web_search.google_cse_id`** — Google Custom Search Engine ID (for Google Custom Search)

## Security Best Practices

- Never commit API keys to version control -- use environment variables
- Rotate keys per provider recommendations
- Set spending limits in provider dashboards
- Monitor usage to detect anomalies

## Detailed Documentation

### Configuration Reference

- **[Providers](/cli/configuration/ai/providers)** - Provider settings, supported models, cloud/local/enterprise configs
- **[Tools](/cli/configuration/ai/tools)** - Tool execution settings, available tools, permission modes
- **[Sessions](/cli/configuration/ai/sessions)** - Session persistence, auto-compact configuration
- **[Skills](/cli/configuration/ai/skills)** - Custom skill schema, tool access, skill examples
- **[Instructions](/cli/configuration/ai/instructions)** - Project instructions settings, ATMOS.md sections

### Guides and Concepts

- **[MCP Server](/ai/mcp-server)** - Universal MCP integration for Claude Desktop and other clients (requires separate `mcp.enabled: true`)
- **[Claude Code Integration](/ai/claude-code-integration)** - IDE integration with Claude Code
- **[Troubleshooting](/ai/troubleshooting)** - Common issues and solutions

## Related Commands