# 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" or "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
    require_confirmation: true
    allowed_tools: []
    restricted_tools: []
    blocked_tools: []

  # 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`
  , 
  `grok`
  , 
  `ollama`
  , 
  `bedrock`
  , 
  `azureopenai`
  . 
  **CLI providers:**
   
  `claude-code`
  , 
  `codex-cli`
  , 
  `gemini-cli`
  .
- **`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`
  )
- **`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 10 AI providers (7 API + 3 CLI). 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-2.5-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