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 — 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 — 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 — add --ai to any command for instant analysis of its output.
• Agent Skills — install and share domain knowledge that any Agent Skills-compatible tool can use.
• Editor & Assistant Setup — wire all of the above into Claude Code, Cursor, Windsurf, and other coding assistants.

Experimental

Quick Start

With API Tokens

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

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.

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

Install and authenticate

# 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

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

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

Interactive chat with session management, provider switching, and skill selection.

atmos ai ask

Ask a single question and get an immediate response. Ideal for scripting and CI/CD.

atmos ai exec

Execute Atmos and shell commands via AI prompts with structured output.

atmos 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

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

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

Try the MCP Example

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

Browse Example

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.

# 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

Agent Skills

Atmos ships 25 agent skills that give AI coding assistants deep knowledge of Atmos conventions. Skills follow the Agent Skills open standard and work across Claude Code, Gemini CLI, OpenAI Codex, Cursor, Windsurf, GitHub Copilot, and more.

atmos ai skill

Install, list, and uninstall community AI skills from GitHub.

Agent Skills Overview

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

Skill Marketplace

Install and share community skills from GitHub.

Skills Configuration

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

Claude Code Integration

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

Claude Code Guide

Commands

atmos --ai

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 for the full atmos mcp command reference.

Troubleshooting

Having issues? See the Troubleshooting Guide for solutions to common problems with providers, tools, sessions, and connectivity.