> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airun.me/llms.txt
> Use this file to discover all available pages before exploring further.

# ai

> Universal AI prompt interpreter — runs Claude Code and Codex CLI with a single command

The `ai` command is the primary entry point for Andi AIRun. It supports multiple AI runtimes (Claude Code, Codex CLI), runs AI prompts as scripts, provides executable markdown with shebang support, and enables cross-cloud provider switching.

## Syntax

```bash theme={null}
ai [OPTIONS] [file.md]
ai update
```

## Usage Modes

### Interactive Mode

Run `ai` with no arguments to start an interactive session:

```bash theme={null}
ai                                        # Regular Claude subscription
ai --aws --opus --team                    # AWS Bedrock with Opus + Agent Teams
ai --ollama --bypass                      # Ollama local with bypassPermissions
ai --vercel --model openai/gpt-5.2-codex  # Vercel AI Gateway
ai --codex                                # Codex CLI with OpenAI API
ai --codex --high --effort max            # Codex with flagship model + max reasoning
```

Interactive mode launches Claude Code with your selected provider and model configuration. The session is automatically restored to your original settings on exit.

### Script File Mode

Execute a markdown file as a prompt:

```bash theme={null}
ai task.md                    # Uses default provider
ai --aws --opus script.md     # AWS Bedrock with Opus
ai --ollama --haiku task.md   # Local Ollama with Haiku tier
```

Script files can contain a shebang line for direct execution:

```markdown theme={null}
#!/usr/bin/env ai
Analyze this codebase and summarize the architecture.
```

```bash theme={null}
chmod +x task.md
./task.md                     # Executes directly
```

### Stdin Mode

Pipe content directly to `ai`:

```bash theme={null}
echo "Explain what a Makefile does" | ai
curl https://example.com/prompt.md | ai
git log -10 | ai --aws
cat data.json | ./analyze.md > results.txt
```

By default, piped content is prepended to file content. Use `--stdin-position append` to place it after.

## Common Options

These are the AI Runner-specific options. See individual reference pages for detailed documentation:

<CardGroup cols={2}>
  <Card title="Provider Flags" icon="cloud" href="./provider-flags">
    Switch between Claude subscriptions and cloud providers
  </Card>

  <Card title="Model Flags" icon="brain" href="./model-flags">
    Select model tiers or specific model IDs
  </Card>

  <Card title="Permission Flags" icon="shield" href="./permission-flags">
    Control file access and command execution permissions
  </Card>

  <Card title="Output Flags" icon="terminal" href="./output-flags">
    Configure output format and streaming behavior
  </Card>
</CardGroup>

## Flag Precedence

When the same configuration is specified in multiple places, AI Runner uses this precedence order (highest to lowest):

1. **CLI flags** - `ai --aws --opus file.md`
2. **Shebang flags** - `#!/usr/bin/env -S ai --aws --opus`
3. **Saved defaults** - `ai --aws --opus --set-default`
4. **Auto-detection** - Current Claude subscription

CLI flags always override shebang flags, which override saved defaults.

## Real Examples

### Basic Script Execution

```bash theme={null}
# Create an executable prompt
cat > greet.md << 'EOF'
#!/usr/bin/env ai
Say hello and tell me a joke.
EOF

chmod +x greet.md
./greet.md
```

### Provider Switching

```bash theme={null}
# Run with local Ollama (free, no API key needed)
ai --ollama task.md

# Run with AWS Bedrock using the strongest model
ai --aws --opus task.md

# Pipe a remote script to a local model
curl https://example.com/prompt.md | ai --ollama
```

### Unix Pipeline Automation

```bash theme={null}
# Pipe in data, redirect output
cat data.json | ./analyze.md > results.txt

# Feed git history to AI
git log -10 | ./summarize.md

# Chain scripts together
./generate.md | ./review.md > final.txt
```

### Agent Teams

```bash theme={null}
# Start an interactive session with agent teams on AWS
ai --aws --opus --team

# Use tmux split panes for teammate display
ai --team --teammate-mode tmux
```

### Persistent Defaults

```bash theme={null}
# Save AWS + Opus as your default
ai --aws --opus --set-default

# Now just run 'ai' - uses saved default
ai task.md

# Clear saved defaults
ai --clear-default
```

## Script Variables

Declare variables with defaults in YAML front-matter:

```markdown theme={null}
#!/usr/bin/env -S ai --haiku
---
vars:
  topic: "machine learning"
  style: casual
  length: short
---
Write a {{length}} summary of {{topic}} in a {{style}} tone.
```

Override from CLI (hyphens normalize to underscores):

```bash theme={null}
./summarize.md --topic "AI safety" --style formal
```

## Other Commands

<ParamField path="update" type="command">
  Update AI Runner to the latest version:

  ```bash theme={null}
  ai update
  ```

  Pulls the latest version from the configured GitHub repository and re-runs the setup script.
</ParamField>

<ParamField path="--set-default" type="flag">
  Save current runtime+provider+model as persistent default:

  ```bash theme={null}
  ai --aws --opus --set-default
  ```
</ParamField>

<ParamField path="--clear-default" type="flag">
  Remove saved defaults:

  ```bash theme={null}
  ai --clear-default
  ```
</ParamField>

<ParamField path="--resume" type="flag">
  Resume the most recent conversation:

  ```bash theme={null}
  ai --resume
  ai --aws --resume           # Resume with different provider
  ai --aws --opus --resume    # Resume with different model
  ```

  Picks up your previous conversation exactly where you left off. Works across provider switches - useful when you hit rate limits.
</ParamField>

<ParamField path="--team" type="flag">
  Enable agent teams (interactive mode only):

  ```bash theme={null}
  ai --team
  ai --aws --opus --team
  ai --team --teammate-mode tmux
  ```

  Enables Claude Code's agent teams feature. Multiple AI agents collaborate on tasks with one lead coordinator.

  **Short form:** `--teams`
</ParamField>

<ParamField path="--tool" type="flag">
  Select the underlying AI runtime:

  ```bash theme={null}
  ai --tool cc               # Claude Code (default)
  ai --tool codex            # Codex CLI (OpenAI)
  ai --cc                    # Shorthand for Claude Code
  ai --codex                 # Shorthand for Codex CLI
  ```

  Auto-detects if not specified: tries Claude Code first, falls back to Codex.
</ParamField>

<ParamField path="--codex" type="flag">
  Shorthand for `--tool codex` (Codex CLI):

  ```bash theme={null}
  ai --codex                 # Interactive Codex session
  ai --codex task.md         # Script mode with Codex
  ai --codex --high          # Codex with gpt-5.4
  ```
</ParamField>

<ParamField path="--effort" type="flag">
  Set reasoning effort level:

  ```bash theme={null}
  ai --effort low task.md      # Minimal reasoning
  ai --effort high task.md     # Deep reasoning
  ai --effort max task.md      # Maximum (Opus only for Claude Code)
  ```

  Works with both runtimes. See [Tool Flags](/cli/tool-flags) for the mapping table.
</ParamField>

<ParamField path="--profile" type="flag">
  Select a Codex CLI config profile (Codex only):

  ```bash theme={null}
  ai --codex --profile azure task.md
  ai --codex --profile openrouter task.md
  ```

  See [Tool Flags](/cli/tool-flags) for configuration details.
</ParamField>

<ParamField path="--auto" type="flag">
  Smart auto-approve (AI classifier for Claude Code, sandbox for Codex):

  ```bash theme={null}
  ai --auto task.md           # Auto-approve safe actions
  ```

  **Short form for:** Claude Code: `--permission-mode auto`, Codex: `--full-auto`
</ParamField>

<ParamField path="--version" type="flag">
  Show version information:

  ```bash theme={null}
  ai --version
  ai -v
  ```
</ParamField>

<ParamField path="--help" type="flag">
  Show help message:

  ```bash theme={null}
  ai --help
  ai -h
  ```
</ParamField>

## Session Behavior

AI Runner uses session-scoped configuration:

* On exit, your original Claude settings are automatically restored
* Plain `claude` in another terminal is completely unaffected
* No global configuration is changed
* Each invocation starts fresh (nested scripts don't inherit parent env vars)

## Passthrough Flags

Any flag not recognized by AI Runner is forwarded to the underlying runtime unchanged:

```bash theme={null}
ai --verbose task.md                    # --verbose passed to Claude Code
ai --allowedTools 'Bash' 'Read' task.md # --allowedTools passed through
ai --chrome --live test-flow.md         # --chrome passed through
```

## Exit Codes

`ai` exits with the same code as the underlying runtime. A non-zero exit means the runtime reported an error.

## Related Commands

<CardGroup cols={3}>
  <Card title="ai-status" href="./ai-status">
    Show current configuration
  </Card>

  <Card title="ai-sessions" href="./ai-sessions">
    List active sessions
  </Card>

  <Card title="ai update" href="./ai-update">
    Update to latest version
  </Card>
</CardGroup>