# Atmos AI

Atmos works with your existing AI tools and brings its own native, built-in capabilities.
Use **API providers** with purchased tokens (Anthropic, OpenAI, Bedrock, Azure OpenAI, Gemini, Grok, Ollama),
or use **CLI providers** that reuse your existing subscription (Claude Code, OpenAI Codex, Gemini CLI) — no API keys needed.

> ⚠️ Experimental

## Quick Start

### With API Tokens

**File:** `atmos.yaml`

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

### With Your Existing Subscription (No API Key)

Use your locally installed Claude Code, OpenAI Codex, or Gemini CLI binary. The CLI tool handles auth via its own subscription — no API key configuration 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
# Claude Code
brew install --cask claude-code && claude auth login

# OpenAI Codex
npm install -g @openai/codex && codex login

# Gemini CLI (authenticates on first run)
npm install -g @google/gemini-cli && gemini
```

```shell
export ANTHROPIC_API_KEY="your-api-key"
atmos ai chat                                        # Interactive chat
atmos ai ask "What stacks do we have?"               # Single question
atmos ai exec "validate stacks" --format json        # CI/CD automation
atmos ai sessions list                               # List sessions
atmos ai skill list                                  # List installed skills
atmos terraform plan vpc -s prod --ai                                       # AI analysis of any command
atmos terraform plan vpc -s prod --ai --skill atmos-terraform               # With domain expertise
atmos terraform plan vpc -s prod --ai --skill atmos-terraform,atmos-stacks  # Multiple skills
```

**AI Configuration**

Configure AI providers, models, API keys, skills, tools, sessions, and instructions in your `atmos.yaml`.

Configuration Reference[Read more](/cli/configuration/ai)

## Examples

**AI with API Providers**

Multi-provider AI configuration with sessions, tools, and custom skills using API tokens.

Browse Example[Read more](/examples/ai)

**AI with Claude Code CLI**

Use your Claude Pro/Max subscription with MCP server pass-through for AWS tools. No API keys needed.

Browse Example[Read more](/examples/ai-claude-code)

## AI Providers

Atmos supports two types of AI providers:

**API providers** call the provider's API directly with purchased tokens. Atmos manages the tool execution loop in-process.

| Provider      | Config Key    | Auth                   |
|---------------|---------------|------------------------|
| Anthropic     | `anthropic`   | `ANTHROPIC_API_KEY`    |
| OpenAI        | `openai`      | `OPENAI_API_KEY`       |
| Google Gemini | `gemini`      | `GEMINI_API_KEY`       |
| Grok (xAI)    | `grok`        | `XAI_API_KEY`          |
| AWS Bedrock   | `bedrock`     | AWS IAM credentials    |
| Azure OpenAI  | `azureopenai` | `AZURE_OPENAI_API_KEY` |
| Ollama        | `ollama`      | None (local)           |

**CLI providers** invoke a locally installed AI tool as a subprocess, reusing your existing subscription.
The CLI tool manages its own tool execution loop, and MCP servers are passed through for tool access.

| Provider     | Config Key    | Binary   | Auth                          | MCP                           |
|--------------|---------------|----------|-------------------------------|-------------------------------|
| Claude Code  | `claude-code` | `claude` | Claude Pro/Max subscription   | Full                          |
| OpenAI Codex | `codex-cli`   | `codex`  | ChatGPT Plus/Pro subscription | Full                          |
| Gemini CLI   | `gemini-cli`  | `gemini` | Google account (free tier)    | Blocked for personal accounts |

:::tip When to use which

- **Interactive development with MCP** — `claude-code` or `codex-cli` (subscription, full MCP), or any of the API providers
- **CI/CD pipelines** — API providers (env var auth, no interactive login)
- **Cost-conscious** — `gemini-cli` (free tier, prompt-only)
- **Enterprise** — `bedrock` or `azureopenai` (compliance, audit trails)
  :::

## AI-Powered Command Analysis

Add `--ai` to any Atmos command for instant AI-powered output analysis. Pair with `--skill` for
domain-specific expertise — multiple skills can be combined with commas or repeated flags.

```bash
# Basic AI analysis
atmos terraform plan vpc -s prod --ai

# Single skill for domain expertise
atmos terraform plan vpc -s prod --ai --skill atmos-terraform

# Multiple skills (comma-separated)
atmos terraform plan vpc -s prod --ai --skill atmos-terraform,atmos-stacks

# Multiple skills (repeated flag)
atmos terraform plan vpc -s prod --ai --skill atmos-terraform --skill atmos-stacks

# Via environment variables
ATMOS_AI=true ATMOS_SKILL=atmos-terraform,atmos-stacks atmos terraform plan vpc -s prod
```

**AI-Powered Command Analysis**

Add `--ai` to any Atmos command for instant output analysis. Combine with `--skill` for domain-specific expertise.
Multiple skills can be specified with commas (`--skill a,b`) or repeated flags (`--skill a --skill b`).

Global Flags Reference[Read more](/cli/global-flags)

## Commands

- **[`atmos ai chat`](/cli/commands/ai/chat)**
  Interactive chat with session management, provider switching, and skill selection.
- **[`atmos ai ask`](/cli/commands/ai/ask)**
  Ask a single question and get an immediate response. Ideal for scripting and CI/CD.
- **[`atmos ai exec`](/cli/commands/ai/exec)**
  Execute Atmos and shell commands via AI prompts with structured output.
- **[`atmos ai sessions`](/cli/commands/ai/sessions)**
  Manage chat sessions: list, clean, export, and import.
- **[`atmos ai skill`](/cli/commands/ai/skill)**
  Install, list, and uninstall community AI skills from GitHub.
- **[`atmos --ai`](/cli/global-flags)**
  Add 
  `--ai`
   flag to any command for AI-powered output analysis. Use 
  `--skill`
   flag for domain-specific expertise (supports multiple skills via commas or repeated flag).
- **[`atmos mcp start`](/cli/commands/mcp/start)**
  Start the Atmos MCP server for external AI clients.
- **[`atmos mcp list`](/cli/commands/mcp/list)**
  List configured external MCP servers.
- **[`atmos mcp tools`](/cli/commands/mcp/tools)**
  List tools from an external MCP server.
- **[`atmos mcp test`](/cli/commands/mcp/test)**
  Test connectivity to an external MCP server.
- **[`atmos mcp status`](/cli/commands/mcp/status)**
  Show live connection status of all configured MCP servers.
- **[`atmos mcp restart`](/cli/commands/mcp/restart)**
  Restart an external MCP server.
- **[`atmos mcp export`](/cli/commands/mcp/export)**
  Export 
  `.mcp.json`
   from 
  `atmos.yaml`
   for Claude Code / Cursor / IDE integration.

## AI Assistants

**Configure AI Assistants**

Set up Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, OpenAI Codex, and other AI coding assistants to use Atmos agent skills.

Setup Guide[Read more](/projects/setup-editor/ai-assistants)

## Claude Code Integration

**Claude Code Integration**

Use Claude Code with the Atmos MCP server and create specialized `atmos-expert` subagents for deep infrastructure expertise.

Claude Code Guide[Read more](/ai/claude-code-integration)

## Agent Skills

Atmos ships 21+ agent skills that give AI coding assistants deep knowledge of Atmos conventions.
Skills follow the [Agent Skills](https://agentskills.io) open standard and work across Claude Code,
Gemini CLI, OpenAI Codex, Cursor, Windsurf, GitHub Copilot, and more.

### [Agent Skills Overview](/ai/agent-skills)

How skills work, available skills, and the SKILL.md format.

### [Skill Marketplace](/ai/skill-marketplace)

Install and share community skills from GitHub.

### [Skills Configuration](/cli/configuration/ai/skills)

Configure skills in `atmos.yaml`.

## MCP

Atmos supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP) in both directions:

**Atmos as MCP Server** — Exposes Atmos AI tools to external clients (Claude Desktop, Claude Code,
VS Code, Cursor, Gemini CLI). Use Atmos tools inside your preferred AI assistant.

**External MCP Servers** — Connect to AWS, GCP, Azure, and custom MCP servers. Their tools become available
in `atmos ai chat`, `atmos ai ask`, and `atmos ai exec` alongside native Atmos tools.

**Smart Routing** — When multiple MCP servers are configured with API providers, Atmos automatically selects
only the servers relevant to your question using a lightweight routing call. This keeps tool payloads small
and responses fast. Use the `--mcp` flag to override and specify servers directly.

**MCP Pass-Through** — With CLI AI providers (`claude-code`, `codex-cli`), all configured MCP servers are
passed to the CLI tool via its native config format. The CLI tool decides which servers to use.
Smart routing is skipped — the AI model handles server selection internally.

:::note CLI Provider MCP

- **Claude Code**: MCP servers passed via `--mcp-config` temp file
- **Codex CLI**: MCP servers written to `~/.codex/config.toml` (backup/restore)
- **Gemini CLI**: MCP blocked for personal Google accounts (`oauth-personal` auth)
  :::

```bash
# Manage external MCP servers
atmos mcp list                    # See configured servers
atmos mcp test aws-docs           # Test connectivity
atmos mcp tools aws-security      # List available tools
atmos mcp status                  # Show live status of all servers
atmos mcp export                  # Export .mcp.json for Claude Code / IDE

# Ask questions — AI auto-routes to the right MCP server
atmos ai ask "What did we spend on EC2 last month?"     # routes to aws-billing
atmos ai ask "Is GuardDuty enabled in us-east-1?"       # routes to aws-security
atmos ai ask "How do I configure S3 lifecycle rules?"   # routes to aws-docs

# Manual MCP server(s) selection (skip auto-routing)
atmos ai ask --mcp aws-iam "List all admin roles"
atmos ai ask --mcp aws-iam,aws-cloudtrail "Who accessed the admin role?"
atmos ai chat --mcp aws-billing
```

**File:** `atmos.yaml`

```yaml
mcp:
  servers:
    # FinOps
    aws-billing:
      command: uvx
      args: ["awslabs.billing-cost-management-mcp-server@latest"]
      env: { AWS_REGION: "us-east-1" }
      description: "AWS Billing — billing summaries and payment history"
      identity: "readonly"   # Atmos Auth identity (from the auth section)

    # Security & Compliance
    aws-security:
      command: uvx
      args: ["awslabs.well-architected-security-mcp-server@latest"]
      env: { AWS_REGION: "us-east-1" }
      description: "AWS Security — Well-Architected security posture assessment"
      identity: "readonly"   # Atmos Auth identity (from the auth section)

    # Documentation (no credentials needed)
    aws-docs:
      command: uvx
      args: ["awslabs.aws-documentation-mcp-server@latest"]
      description: "AWS Documentation — search and fetch AWS docs"

  # Smart routing (enabled by default, uses your configured AI provider)
  routing:
    enabled: true
```

**MCP Configuration**

Configure the Atmos MCP server and external MCP server connections.

Configuration Reference[Read more](/cli/configuration/mcp)

**Try the MCP Example**

Explore a complete example with pre-configured AWS MCP servers for cost analysis, security, IAM, and documentation.

Browse Example[Read more](/examples/mcp)

## Troubleshooting

Having issues? See the [Troubleshooting Guide](/ai/troubleshooting) for solutions to common problems
with providers, tools, sessions, and connectivity.