# AI Tools

The `ai.tools` section controls which Atmos commands the AI assistant can execute and whether user
confirmation is required.

> ⚠️ Experimental

## How Tool Calling Works

When you ask a question that requires infrastructure data, the AI decides which tool to call, requests permission (if configured), executes the tool locally, and uses the result to answer your question.

```mermaid
sequenceDiagram
    participant User
    participant AtmosAI as Atmos AI Chat
    participant LLM as AI Provider (Claude)
    participant Tools as Local Tools
    participant Files as Local Files

    User->>AtmosAI: "What's the VPC CIDR in prod-use1?"
    AtmosAI->>LLM: Send message + tool definitions (metadata only)
    Note over LLM: AI analyzes question<br/>Determines it needs tool
    LLM->>AtmosAI: Response: "I need atmos_describe_component"
    AtmosAI->>User: Request permission (if required)
    User->>AtmosAI: Approve
    AtmosAI->>Tools: Execute: describe_component(vpc, prod-use1)
    Tools->>Files: Read local stack/component files
    Files-->>Tools: Component configuration
    Tools-->>AtmosAI: Tool result with CIDR info
    AtmosAI->>LLM: Send tool results
    LLM->>AtmosAI: Final answer with CIDR
    AtmosAI->>User: "The VPC CIDR is 10.0.0.0/16"
```

### What Gets Sent to the AI Provider

Only **metadata** is sent initially — tool definitions (names, parameters, descriptions) and your question. No actual infrastructure data leaves your machine until the AI specifically requests it by calling a tool.

When the AI calls a tool, it runs **locally** and only the tool's output is sent back. You control this through the [permission system](#permission-modes).

## Configuration

**File:** `atmos.yaml`

```yaml
ai:
  tools:
    enabled: true
    require_confirmation: true
    allowed_tools:
      - atmos_describe_component
      - atmos_list_stacks
      - atmos_validate_stacks
      - atmos_describe_*            # Wildcard patterns supported
    restricted_tools:
      - write_component_file
      - write_stack_file
      - edit_file
    blocked_tools:
      - execute_bash_command
    yolo_mode: false                # Skip all confirmations (DANGEROUS!)
```

## Tool Settings

- **`tools.enabled`**
  Enable or disable AI tool execution (default: 
  `false`
  ). When disabled, the AI can only answer from its training data and conversation context.
- **`tools.require_confirmation`**
  Prompt the user before executing any tool (default: 
  `true`
  ). Set to 
  `false`
   to allow all tools except 
  `restricted_tools`
   to execute automatically.
- **`tools.allowed_tools`**
  List of tools that execute without confirmation, even when 
  `require_confirmation: true`
  . Supports wildcard patterns like 
  `atmos_describe_*`
   (default: 
  `[]`
  ).
- **`tools.restricted_tools`**
  List of tools that always require user confirmation, even when 
  `require_confirmation: false`
   (default: 
  `[]`
  ). Use this to protect write and execute operations.
- **`tools.blocked_tools`**
  List of tools completely blocked from execution (default: 
  `[]`
  ). The AI cannot invoke these tools under any circumstances.
- **`tools.yolo_mode`**
  Skip all permission checks and execute tools immediately (default: 
  `false`
  ). Only use in trusted, isolated CI/CD environments. 
  **Never use in production or shared environments.**

## Available Tools

### Atmos Commands

- **`atmos_describe_component`**
  Describe a component's configuration in a stack. Read-only.
- **`atmos_list_stacks`**
  List all available stacks. Read-only.
- **`atmos_validate_stacks`**
  Validate stack configurations against schemas and policies. Read-only.
- **`describe_affected`**
  Show components affected by git changes. Read-only.
- **`get_template_context`**
  Debug Go template variable context. Read-only.
- **`execute_atmos_command`**
  Execute any Atmos CLI command. Permissions vary by command.

### File Operations

- **`read_file`**
  Read any file from the repository. Read-only.
- **`read_component_file`**
  Read a file from the components directory. Read-only.
- **`read_stack_file`**
  Read a file from the stacks directory. Read-only.
- **`list_component_files`**
  List files in a component directory. Read-only.
- **`search_files`**
  Search for patterns across files. Read-only.
- **`edit_file`**
  Edit an existing file with targeted changes. Requires confirmation by default.
- **`write_component_file`**
  Write or modify a component file. Requires confirmation by default.
- **`write_stack_file`**
  Write or modify a stack file. Requires confirmation by default.

### Execution

- **`execute_bash_command`**
  Execute shell commands. Requires confirmation by default.

### Validation and Web

- **`validate_file_lsp`**
  Validate files using LSP diagnostics (
  [requires LSP](/lsp/lsp-client)
  ). Read-only.
- **`web_search`**
  Search the web via DuckDuckGo or Google. Requires confirmation by default.

All file operations include **path traversal protection** -- files can only be accessed within configured directories.

### Web Search Configuration

**File:** `atmos.yaml`

```yaml
ai:
  web_search:
    enabled: true
    max_results: 10
    # Google Custom Search (optional)
    # google_api_key: !env "GOOGLE_API_KEY"
    # google_cse_id: !env "GOOGLE_CSE_ID"
```

See [Web Search](/cli/configuration/ai#web-search) in the AI configuration reference for all settings.

## Permission Modes

- ****Prompt** (default)**
  Set 
  `require_confirmation: true`
  . Ask before each tool execution. The most secure mode.
- ****Allow****
  Set 
  `require_confirmation: false`
  . Auto-execute all tools except those in 
  `restricted_tools`
  .
- ****YOLO****
  Set 
  `yolo_mode: true`
  . Skip all permission checks. Only use in isolated CI/CD environments.

### Permission Flow

```
1. YOLO Mode?     → Yes → Execute immediately
2. Blocked?       → Yes → Deny
3. Allowed list?  → Yes → Execute without prompt
4. Restricted?    → Yes → Always prompt
5. Default        → Prompt if require_confirmation is true
```

### Permission Prompts

When a tool requires confirmation:

```
Tool Execution Request
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Tool: atmos_describe_component
Description: Describe an Atmos component configuration in a specific stack

Parameters:
  component: vpc
  stack: prod-use1

Options:
  [a] Always allow (save to .atmos/ai.settings.local.json)
  [y] Allow once
  [n] Deny once
  [d] Always deny (save to .atmos/ai.settings.local.json)

Choice (a/y/n/d):
```

## Wildcard Patterns

Tool lists support glob-style wildcard patterns:

```yaml
allowed_tools:
  - atmos_describe_*      # Match all describe commands
  - atmos_list_*          # Match all list commands
  - *_validate            # Match anything ending in _validate
```

## Persistent Permission Cache

"Always allow" and "always deny" choices from interactive prompts are saved to `.atmos/ai.settings.local.json`. This file is user-specific and gitignored by default.

**Priority order:** Blocked tools (config) > Cached denials > Allowed tools (config) > Cached allowances > Restricted tools > Default behavior.

## Skill-Specific Tool Access

Each [AI skill](/cli/configuration/ai/skills) defines which tools it can use, creating a safety layer where specialized skills only perform actions relevant to their purpose.

- ****General****
  Can read all, write all, execute all. Full access (respects global config).
- ****atmos-stacks****
  Can read stacks, components, files. No write or execute. Analysis only.
- ****atmos-components****
  Can read components, files. Can write and execute (with confirmation). Code-focused.
- ****atmos-terraform****
  Can read stacks, components, files. No write. Can execute (with confirmation). Plan/review only.
- ****atmos-validation****
  Can read stacks, files, LSP. No write or execute. Validation only.

**Workflow tip:** Use different skills for different phases — analyze with `atmos-stacks`, refactor with `atmos-components`, validate with `atmos-validation`. Switch skills with **Ctrl+A** in the chat TUI.

## Security Best Practices

**Start conservative.** The default (prompt for everything) is the most secure. Relax permissions over time as you build trust:

**File:** `atmos.yaml`

```yaml
# Production: very restrictive
ai:
  tools:
    enabled: true
    allowed_tools: []              # Prompt for everything
    blocked_tools:
      - execute_*                  # Block all execution tools
      - write_*                    # Block all write operations

# Development: more permissive
ai:
  tools:
    enabled: true
    allowed_tools:
      - atmos_describe_*           # Auto-approve read-only
      - atmos_list_*
      - atmos_validate_*
    blocked_tools:
      - execute_bash_command       # Block shell execution
```

:::warning YOLO Mode
Never use `yolo_mode` in production, shared environments, or workstations with production access. Reserve it for isolated CI/CD runners and sandboxed testing.
:::

## Troubleshooting

**Tools not executing:** Check `tools.enabled: true` in your config and verify the tool isn't in `blocked_tools`.

**No permission prompts:** The tool may be in `allowed_tools` or you may have previously chosen "always allow" in `.atmos/ai.settings.local.json`. Delete the cache file to reset.

**Timeouts:** Tools have a 30-second timeout. Long-running operations are automatically cancelled. Run them manually if needed.

## Related Documentation

- [AI Configuration](/cli/configuration/ai) - Configure AI providers and settings
- [AI Skills](/cli/configuration/ai/skills) - Skill system and custom skill creation
- [AI Sessions](/cli/configuration/ai/sessions) - Persistent conversation sessions