# Atmos AI

Atmos is designed for AI agents to operate your infrastructure directly. It can call MCP servers and be called as one, reason about your infrastructure on its own, and share the same skills and context with whatever AI tool your team already uses.

Together, these make it easier for a team to work with the infrastructure and repositories Atmos manages — whichever AI tool each person happens to be using.

- **[Agent Harness](#agent-harness)** — chat, ask, or script against your infrastructure with `atmos ai chat`/`ask`/`exec`, using either API tokens or your existing Claude Code/Codex/Copilot/Gemini subscription.
- **[MCP](#mcp)** — connect Atmos to external MCP servers as a client, expose Atmos's own tools as a server, and distribute MCP server configuration from `atmos.yaml` so Atmos and every agent harness on your team use the same servers.
- **[Command Analysis](#ai-powered-command-analysis)** — add `--ai` to any command for instant analysis of its output.
- **[Agent Skills](#agent-skills)** — install and share domain knowledge that any Agent Skills-compatible tool can use.
- **[Editor & Assistant Setup](#ai-assistants--editor-integration)** — wire all of the above into Claude Code, Cursor, Windsurf, and other coding assistants.

> ⚠️ 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, GitHub Copilot, or Gemini CLI binary. The CLI tool handles auth via its own subscription — no API key configuration needed.

:::note Bring your own CLI tool
Atmos assumes one of these is already installed and authenticated on your machine — it doesn't
install or log you into `claude`/`codex`/`copilot`/`gemini` for you. If you don't have one yet,
the commands below install and authenticate each.
:::

**File:** `atmos.yaml`

```yaml
ai:
  enabled: true
  default_provider: "claude-code"  # or "codex-cli", "copilot-cli", "gemini-cli", or "auto" to auto-detect
  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

# GitHub Copilot CLI
npm install -g @github/copilot && copilot   # then /login (or set GH_TOKEN)

# 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)

## Agent Harness

Atmos can act as an agent harness in its own right — `atmos ai chat`, `ask`, and `exec` talk to your infrastructure directly, without you opening a separate AI tool. Point it at an **API provider** (Atmos manages the tool-execution loop itself) or a **CLI provider** that reuses a subscription you already have.

**API providers** call the provider's API directly with purchased tokens.

| 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`          |
| GitHub Models | `github`      | `GITHUB_TOKEN`         |
| 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                          |
| GitHub Copilot | `copilot-cli` | `copilot` | Copilot subscription (`/login` or `GH_TOKEN`) | 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); `github` is zero-secret in GitHub Actions (built-in `GITHUB_TOKEN` with `permissions: models: read`)
- **Cost-conscious** — `gemini-cli` (free tier, prompt-only)
- **Enterprise** — `bedrock` or `azureopenai` (compliance, audit trails)
  :::

* **[`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.

**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)

## MCP

Atmos can use external MCP servers (AWS, GCP, custom tooling) as a client, and expose its own tools as a server — both directions can be enabled at once, and the same servers work whether you're inside `atmos ai chat` or handing them to Claude Code, Cursor, or another coding assistant.

**MCP Documentation**

Full setup for both directions: adding servers, installing into your AI client, smart routing vs. CLI pass-through, and the complete command reference.

MCP Documentation[Read more](/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)

## 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.

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

## Agent Skills

Atmos ships 25 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.

- **[`atmos ai skill`](/cli/commands/ai/skill)**
  Install, list, and uninstall community AI skills from GitHub.

### [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`.

## AI Assistants & Editor Integration

**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**

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)

## Commands

- **[`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).

See [MCP Documentation](/mcp#managing-servers) for the full `atmos mcp` command reference.

## Troubleshooting

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