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

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

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.

Configuration

atmos.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, the AI can only answer from its training data and conversation context. This does not affect atmos mcp start — see MCP 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 tool requests from the claude-code provider.
tools.allowed: When non-empty, restricts which tools exist at all — only tools matching one of these name patterns are registered; every other tool simply isn't available 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 completely blocked from execution (default: []). The AI cannot invoke these tools, except when mode: yolo bypasses the check.
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.

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.

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

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

mode: yolo?     → Yes → Execute immediately
Blocked?        → Yes → Deny
mode: allow?    → Yes → Execute without prompt
Allowed list?   → Yes → Execute without prompt
Restricted?     → Yes → Always prompt
Default         → Prompt

The same flow applies to every tool request, whether the request comes from Atmos's own tool loop (API providers) or from the claude-code provider. 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 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. Other tools are remembered by tool name.

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:

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

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

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.

AI Configuration - Configure AI providers and settings
AI Skills - Skill system and custom skill creation
AI Sessions - Persistent conversation sessions

How Tool Calling Works​

What Gets Sent to the AI Provider​

Configuration​

Tool Settings​

MCP Server Note​

Available Tools​

Atmos Commands​

File Operations​

Execution​

Validation and Web​

Web Search Configuration​

Permission Modes​

Permission Flow​

Permission Prompts​

Command-Scoped Approvals for Bash​

Non-Interactive Runs​

Wildcard Patterns​

Persistent Permission Cache​

Skill-Specific Tool Access​

Security Best Practices​

Troubleshooting​

Related Documentation​

How Tool Calling Works

What Gets Sent to the AI Provider

Configuration

Tool Settings

MCP Server Note

Available Tools

Atmos Commands

File Operations

Execution

Validation and Web

Web Search Configuration

Permission Modes

Permission Flow

Permission Prompts

Command-Scoped Approvals for Bash

Non-Interactive Runs

Wildcard Patterns

Persistent Permission Cache

Skill-Specific Tool Access

Security Best Practices

Troubleshooting

Related Documentation