# AI Tools

The `ai.tools` section controls which Atmos commands the AI assistant can execute and whether user
approval is required before each one runs.

> ⚠️ Experimental

:::note Renamed in a recent release
`tools.allowed_tools`, `tools.restricted_tools`, and `tools.blocked_tools` were renamed to
`tools.allowed`, `tools.restricted`, and `tools.blocked` — the `tools:` block already establishes
what these are lists of. The old names are no longer read; update `atmos.yaml` to the new names.
`tools.allowed` also picked up a second responsibility: see [Tool Settings](#tool-settings) below.
:::

## 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
    mode: require_confirmation      # require_confirmation (default) | allow | yolo
    allowed:
      - atmos_describe_component
      - atmos_list_stacks
      - atmos_validate_stacks
      - atmos_describe_*            # Wildcard patterns supported
    restricted:
      - write_component_file
      - write_stack_file
      - edit_file
    blocked:
      - execute_bash_command
```

## Tool Settings

- **`tools.enabled`**
  Enable or disable the tool subsystem for 
  `atmos ai chat`
  /
  `ask`
  /
  `exec`
   (default: 
  `false`
  ). When disabled, Atmos does not register its tools. CLI providers can still use their native tools. This does 
  **not**
   affect 
  `atmos mcp start`
   — see 
  [MCP note](#mcp-server-note)
   below.
- **`tools.mode`**
  How Atmos approves tool calls (default: 
  `require_confirmation`
  ). One value selects the whole approval behavior: 
  `require_confirmation`
   prompts for each tool that needs approval; 
  `allow`
   never prompts and still honors 
  `blocked`
  ; 
  `yolo`
   never prompts and bypasses the 
  `blocked`
   and 
  `restricted`
   checks (use with care). An unknown value is an error that lists the valid values. When 
  `mode`
   is set it takes precedence over the deprecated 
  `yolo_mode`
   and 
  `require_confirmation`
   settings below, which are then ignored. Applies to 
  `atmos ai chat`
  , 
  `ask`
  , and 
  `exec`
  , including approval requests delegated by the 
  `claude-code`
   provider.
- **`tools.allowed`**
  When non-empty, restricts which Atmos tools are registered — only tools matching one of these name patterns are registered; other Atmos tools are unavailable this session. Listed tools also skip the confirmation prompt. Supports wildcard patterns like 
  `atmos_describe_*`
  . Empty/unset (default: 
  `[]`
  ) means every tool is registered, subject to normal confirmation rules.
- **`tools.restricted`**
  List of tools (from whatever 
  `allowed`
   already let through) that always prompt unless they are also in 
  `allowed`
   (default: 
  `[]`
  ). Applies when 
  `mode`
   is 
  `require_confirmation`
  ; 
  `mode: allow`
   and 
  `mode: yolo`
   never prompt. Use this to protect write and execute operations.
- **`tools.blocked`**
  List of tools denied by Atmos’s permission checker (default: 
  `[]`
  ), except when 
  `mode: yolo`
   bypasses the check. CLI-provider requests that are approved natively or preapproved by the provider do not reach this checker.
- **`tools.yolo_mode` (deprecated)**
  Deprecated alias for 
  `mode: yolo`
   when set to 
  `true`
  . Ignored when 
  `mode`
   is set.
- **`tools.require_confirmation` (deprecated)**
  Deprecated alias. Setting it to 
  `false`
   is the same as 
  `mode: allow`
  , and 
  `true`
   is the same as 
  `mode: require_confirmation`
  . Ignored when 
  `mode`
   is set.

:::note Migrating from the two booleans
Existing `yolo_mode` and `require_confirmation` settings keep working. Replace them with `mode` at your convenience: `yolo_mode: true` becomes `mode: yolo`, and `require_confirmation: false` becomes `mode: allow`.
:::

### MCP Server Note

`atmos mcp start` always registers tools (subject to `tools.allowed`/`restricted`/`blocked`)
regardless of `tools.enabled` — `mcp.enabled: true` is that command's own, sufficient opt-in.
`tools.enabled` only gates `atmos ai chat`/`ask`/`exec`'s own tool-use loop. See
[MCP Configuration](/cli/configuration/mcp).

## 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.
- **`atmos_validate_schema`**
  Validate atmos.yaml (plus atmos.d and profile fragments) and other configured YAML files against their JSON Schemas. 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.
- **`atmos_list_findings`**
  List security findings from AWS Security Hub for Atmos stacks. Read-only.
- **`atmos_describe_finding`**
  Get detailed information about a specific security finding by ID. Read-only.
- **`atmos_analyze_finding`**
  Analyze a security finding using AI to determine root cause and remediation steps. Read-only.
- **`atmos_compliance_report`**
  Generate a compliance posture report for a framework (CIS AWS, PCI DSS, SOC2, HIPAA, NIST). Read-only.
- **`atmos_config_get`**
  Read a value from the active atmos.yaml using a dot-notation path. Read-only.
- **`atmos_config_list`**
  List the dot-notation setting paths defined in the active atmos.yaml. Read-only.
- **`atmos_config_set`**
  Set a value in the active atmos.yaml using a dot-notation path, preserving comments and anchors. Requires confirmation by default.
- **`atmos_config_delete`**
  Delete a value from the active atmos.yaml using a dot-notation path. Requires confirmation by default.
- **`atmos_config_format`**
  Format the active atmos.yaml file in place, preserving comments and anchors. Requires confirmation by default.
- **`atmos_stack_config_get`**
  Read the effective value of a component-relative dot-path for a component in a stack. Read-only.
- **`atmos_stack_config_list`**
  List editable component-relative config paths for a component in a stack. Read-only.
- **`atmos_stack_config_set`**
  Set a component-relative value for a component in a stack, using provenance to find the defining manifest. Requires confirmation by default.
- **`atmos_stack_config_delete`**
  Delete a component-relative value from the manifest that defines it for a component in a stack. Requires confirmation by default.
- **`atmos_stack_config_format`**
  Format the manifest files that define a stack component in place. Requires confirmation by default.
- **`atmos_vendor_config_get`**
  Read a raw value from a vendor manifest (vendor.yaml) by dot-notation path. Read-only.
- **`atmos_vendor_config_list`**
  List raw setting paths from a vendor manifest and its imports. Read-only.
- **`atmos_vendor_config_set`**
  Set a raw value in a vendor manifest by dot-notation path. Requires confirmation by default.
- **`atmos_vendor_config_delete`**
  Delete a raw value from a vendor manifest by dot-notation path. Requires confirmation by default.
- **`atmos_vendor_config_format`**
  Format a vendor manifest file in place, preserving comments and anchors. Requires confirmation by default.
- **`atmos_vendor_check_updates`**
  Check whether vendored Git-sourced components have a newer version available than the one currently pinned. Read-only.
- **`atmos_vendor_diff`**
  Show a unified diff between a vendored component's pinned version and another ref. Read-only.
- **`atmos_vendor_update`**
  Update vendored Git-sourced components' pinned version to the latest available tag. Requires confirmation by default.
- **`atmos_list_commands`**
  List Atmos CLI commands and subcommands. Read-only.
- **`atmos_command_help`**
  Get detailed help for a specific Atmos CLI command. Read-only.
- **`atmos_describe_dependents`**
  List the Atmos components that depend on a given component/stack pair. Read-only.
- **`atmos_describe_workflows`**
  List all Atmos workflows discovered under the configured workflows base path. Read-only.
- **`atmos_list_workflows`**
  List all Atmos workflows with their defining file, description, and step count. Read-only.
- **`atmos_list_components`**
  List unique Atmos components defined across all stacks. Read-only.
- **`atmos_list_values`**
  List a component's values across every stack where it's used. Read-only.
- **`atmos_auth_whoami`**
  Show the currently active Atmos authentication identity and credential status. Read-only.
- **`atmos_auth_list`**
  List configured Atmos authentication providers and identities. Read-only.
- **`atmos_toolchain_list`**
  List tools declared in the project's .tool-versions file. Read-only.
- **`atmos_toolchain_add`**
  Add a tool dependency to the project's .tool-versions file. Requires confirmation by default.
- **`atmos_toolchain_remove`**
  Remove a tool dependency from the project's .tool-versions file. Requires confirmation by default.
- **`atmos_toolchain_set`**
  Set a tool's default pinned version in the project's .tool-versions file. Requires confirmation by default.
- **`atmos_version_track_status`**
  Check every dependency in an Atmos version track against its datasource for available updates. Read-only.
- **`atmos_version_track_add`**
  Add a dependency entry to an Atmos version track. Requires confirmation by default.
- **`atmos_version_track_set`**
  Update fields of an existing Atmos version track dependency entry. Requires confirmation by default.
- **`atmos_version_track_remove`**
  Remove a dependency entry from an Atmos version track. Requires confirmation by default.
- **`atmos_version_track_update`**
  Advance an Atmos version track's locked versions within each entry's update policy. Requires confirmation by default.
- **`atmos_secret_list`**
  List declared secrets and their initialization status. Read-only.
- **`atmos_validate_component`**
  Validate an Atmos component's configuration in a stack using JSON Schema or OPA policies. Read-only.

### 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.
- **`atmos_terraform_component_hcl_get`**
  Read an attribute value or block from a Terraform component file using an hcledit-style HCL address. Read-only.
- **`atmos_terraform_component_hcl_edit`**
  Structurally edit a Terraform component file using hcledit, preserving comments and formatting. 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.
- **`atmos_validate_file`**
  Validate a YAML file against a JSON Schema with line numbers, no LSP required. 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 
  `mode: require_confirmation`
  . Ask before each tool execution that needs approval. The most secure mode.
- ****Allow****
  Set 
  `mode: allow`
  . Run tools without prompting. Tools in 
  `blocked`
   are still denied.
- ****YOLO****
  Set 
  `mode: yolo`
  . Skip all permission checks, including 
  `blocked`
   and 
  `restricted`
  . Only use in isolated CI/CD environments.

### Permission Flow

A tool must first be _registered_ to be callable at all: if `tools.allowed` is non-empty, only
matching tools are registered in the first place. Everything below only applies to a tool that
made it that far:

```
1. mode: yolo?     → Yes → Execute immediately
2. Blocked?        → Yes → Deny
3. mode: allow?    → Yes → Execute without prompt
4. Allowed list?   → Yes → Execute without prompt
5. Restricted?     → Yes → Always prompt
6. Default         → Prompt
```

The same flow applies to Atmos's own tool loop (API providers) and to approval requests
delegated by the `claude-code` provider. Claude-native and provider-preapproved requests follow
Claude’s own permission policy and do not reach this flow. When Claude Code asks to run a tool such as
`Bash`, `Edit`, or an MCP tool, Atmos checks the request against this flow and prompts you in the
terminal if approval is needed. Claude waits for your answer and continues in the same run. See
[Claude Code provider](/cli/configuration/ai/providers#cli-provider-settings) for the provider-side
settings.

### Permission Prompts

When a tool requires confirmation, Atmos shows what the tool is about to do. Long commands are wrapped to the width of your terminal and shown in their own panel:

```
  Permission required ────────────────────────────────────────────────
  Tool  atmos_describe_component
  Why   Describe an Atmos component configuration in a specific stack
  component  vpc
  stack      prod-use1

┃ Allow execution?
┃ "Always" choices are saved to .atmos/ai.settings.local.json
┃ > Allow once
┃   Always allow atmos_describe_component
┃   Deny once
┃   Always deny atmos_describe_component
```

Allow once is the default, so pressing Enter never saves a permanent decision. After you choose, the prompt is replaced by a one-line receipt such as `✓ Allowed Bash: atmos list stacks`.

- ****Allow once****
  Run the tool this time only. This is the default choice.
- ****Always allow****
  Run the tool now and remember the decision in 
  `.atmos/ai.settings.local.json`
  .
- ****Deny once****
  Refuse this call. The model continues and can explain what it could not do.
- ****Always deny****
  Refuse this call and remember the decision in 
  `.atmos/ai.settings.local.json`
  .

Pressing **Ctrl-C** at the prompt aborts the whole run.

### Command-Scoped Approvals for Bash

For the `Bash` tool, "Always allow" applies to the exact command you approved, not to the tool as a whole. Approving `atmos list stacks` saves a rule such as:

```
Bash(atmos list stacks)
```

Running `atmos list stacks` again no longer prompts. A different command, for example `atmos describe stacks`, still prompts. Claude Code also scopes `Read`, `Edit`, `Write`, `NotebookEdit`, `Glob`, `Grep`, and `WebFetch` approvals to the request’s file path, notebook path, search path or pattern, or URL. Examples include `Read(/repo/go.mod)` and `Glob(**/*.go)`. Atmos’s own tools and requests without a specifier, including MCP tools, are remembered by bare tool name, covering later calls with different arguments. Path-scoped rules also cover later changes to that file’s contents. The prompt’s Always choices name the scope being saved.

### Non-Interactive Runs

When approval is needed and no terminal is available (CI, a pipe on stdin, or no TTY), `atmos ai ask` fails with an error instead of waiting for input. The error suggests three ways forward:

- Run the command in a terminal.
- Set `ai.tools.mode: allow` (or `yolo` in an isolated runner).
- Add the tool to `ai.providers.claude-code.allowed_tools`.

For unattended pipelines, prefer a narrow `allowed` list together with `mode: allow` over `mode: yolo`.

## Wildcard Patterns

Tool lists support glob-style wildcard patterns:

```yaml
allowed:
  - 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.

Cached decisions apply to every command that uses the permission system, including `atmos ai ask` with the `claude-code` provider.

**Priority order:** `tools.allowed` (registration filter) > 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: []                    # All tools registered; prompt for everything
    blocked:
      - execute_*                  # Block all execution tools
      - write_*                    # Block all write operations

# Development: more permissive
ai:
  tools:
    enabled: true
    allowed:
      - atmos_*                    # ONLY atmos_* tools are registered, and auto-approved
    blocked:
      - atmos_validate_stacks      # Still registered (it matches atmos_*) but every call is denied
```

Note: `allowed` only controls _registration_ (whether a tool exists this session at all).
`blocked`/`restricted` are checked at _execution_ time, against whatever `allowed` already let
through — a blocked tool can still appear in `tools/list` (MCP) or the AI's tool set, but every
call to it is denied. A tool listed in both `allowed` and `restricted` is auto-approved, not
prompted — `allowed` is checked first, before `restricted`.

:::warning YOLO Mode
Never use `mode: yolo` 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, verify the tool isn't in `blocked`, and — if you've set `tools.allowed` — verify the tool is actually in that list (otherwise it was never registered in the first place).

**No permission prompts:** The tool may be in `allowed`, `mode` may be `allow` or `yolo`, 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