Advanced Configuration

Configuration Files

AI Runner uses a configuration directory at ~/.ai-runner/ (or legacy ~/.claude-switcher/):

~/.ai-runner/
├── secrets.sh          # Your API keys and credentials (user-edited)
├── models.sh           # Model defaults (copied from config/models.sh)
├── banner.sh           # Startup banner (copied from config/banner.sh)
└── defaults.sh         # Saved defaults from --set-default

Key files:

secrets.sh: User-edited file for API keys and model overrides (never overwritten)
models.sh: System defaults (updated by setup.sh when defaults change)
defaults.sh: Persistent provider/model preferences saved with --set-default

Model Overrides in secrets.sh

Override default model identifiers for any provider by adding exports to ~/.ai-runner/secrets.sh:

nano ~/.ai-runner/secrets.sh

AWS Bedrock

# Override AWS models
export CLAUDE_MODEL_SONNET_AWS="global.anthropic.claude-sonnet-4-6"
export CLAUDE_MODEL_OPUS_AWS="global.anthropic.claude-opus-4-8"
export CLAUDE_MODEL_HAIKU_AWS="us.anthropic.claude-haiku-4-5-20251001-v1:0"

# Override small/fast model for background operations
export CLAUDE_SMALL_FAST_MODEL_AWS="us.anthropic.claude-haiku-4-5-20251001-v1:0"

Pin a specific model revision (dated variants are published by Anthropic when available):

export CLAUDE_MODEL_OPUS_AWS="global.anthropic.claude-opus-4-8"

Google Vertex AI

export CLAUDE_MODEL_SONNET_VERTEX="claude-sonnet-4-6"
export CLAUDE_MODEL_OPUS_VERTEX="claude-opus-4-8"
export CLAUDE_MODEL_HAIKU_VERTEX="claude-haiku-4-5@20251001"

export CLAUDE_SMALL_FAST_MODEL_VERTEX="claude-haiku-4-5@20251001"

Anthropic API

export CLAUDE_MODEL_SONNET_ANTHROPIC="claude-sonnet-4-6"
export CLAUDE_MODEL_OPUS_ANTHROPIC="claude-opus-4-8"
export CLAUDE_MODEL_HAIKU_ANTHROPIC="claude-haiku-4-5"

export CLAUDE_SMALL_FAST_MODEL_ANTHROPIC="claude-haiku-4-5"

Microsoft Azure

Model names are deployment names from your Azure portal:

export CLAUDE_MODEL_SONNET_AZURE="claude-sonnet-4-6"
export CLAUDE_MODEL_OPUS_AZURE="claude-opus-4-8"
export CLAUDE_MODEL_HAIKU_AZURE="claude-haiku-4-5"

export CLAUDE_SMALL_FAST_MODEL_AZURE="claude-haiku-4-5"

Vercel AI Gateway

Use provider/model format (dots not dashes in version numbers):

export CLAUDE_MODEL_SONNET_VERCEL="anthropic/claude-sonnet-4.6"
export CLAUDE_MODEL_OPUS_VERCEL="anthropic/claude-opus-4.8"
export CLAUDE_MODEL_HAIKU_VERCEL="anthropic/claude-haiku-4.5"

export CLAUDE_SMALL_FAST_MODEL_VERCEL="anthropic/claude-haiku-4.5"

Non-Anthropic models:

export CLAUDE_MODEL_SONNET_VERCEL="xai/grok-code-fast-1"
export CLAUDE_SMALL_FAST_MODEL_VERCEL="xai/grok-code-fast-1"

Ollama (Local + Cloud)

By default, AI Runner auto-detects available models. Override with:

# Local models (requires 24GB+ VRAM)
export OLLAMA_MODEL_HIGH="qwen3:72b"         # For --opus/--high
export OLLAMA_MODEL_MID="qwen3-coder"        # For --sonnet/--mid
export OLLAMA_MODEL_LOW="gemma3"             # For --haiku/--low

# Cloud models (no GPU required, 198K context)
export OLLAMA_MODEL_HIGH="minimax-m2.5:cloud"  # 80% SWE-bench
export OLLAMA_MODEL_MID="glm-5:cloud"          # 78% SWE-bench
export OLLAMA_MODEL_LOW="glm-5:cloud"

# Background model (optional, defaults to Haiku)
export OLLAMA_SMALL_FAST_MODEL="gemma3"

LM Studio (Local)

By default, AI Runner uses the first loaded model for all tiers. Override:

export LMSTUDIO_HOST="http://localhost:1234"
export LMSTUDIO_MODEL_HIGH="openai/gpt-oss-20b"
export LMSTUDIO_MODEL_MID="openai/gpt-oss-20b"
export LMSTUDIO_MODEL_LOW="ibm/granite-4-micro"

Codex CLI

Override default Codex model tiers in ~/.ai-runner/secrets.sh:

export CODEX_MODEL_HIGH="gpt-5.4"
export CODEX_MODEL_MID="gpt-5.3-codex"
export CODEX_MODEL_LOW="gpt-5.4-mini"

For custom providers (Azure OpenAI, OpenRouter), configure ~/.codex/config.toml directly. See Runtimes.

Pinning Opus to a specific version

AI Runner’s defaults track Anthropic’s current Opus release (4.7 as of 2026-04-16). You may prefer to pin to an older version — common reasons include personal preference for a model’s behavior, a known regression in your workload (e.g. some users report worse long-context recall on 4.7 in very large codebases), or a transient provider-side bug with the newest release. Pinning is a per-user choice and doesn’t affect anyone else. To pin Opus to 4.6 across every provider, add this to ~/.ai-runner/secrets.sh:

# Pin --opus / --high to Opus 4.6 across all providers
export CLAUDE_MODEL_OPUS_AWS="global.anthropic.claude-opus-4-6-v1"
export CLAUDE_MODEL_OPUS_VERTEX="claude-opus-4-6"
export CLAUDE_MODEL_OPUS_ANTHROPIC="claude-opus-4-6"
export CLAUDE_MODEL_OPUS_AZURE="claude-opus-4-6"
export CLAUDE_MODEL_OPUS_VERCEL="anthropic/claude-opus-4.6"

# Also pin Claude Code's /model picker "Default" badge to 4.6.
# Without this, the picker shows "Default ✓ Opus 4.8" even when ANTHROPIC_MODEL=4.6.
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6"

Two knobs are needed:

CLAUDE_MODEL_OPUS_* sets the active session’s model (ANTHROPIC_MODEL) for the relevant provider.
ANTHROPIC_DEFAULT_OPUS_MODEL is a separate Claude Code variable that controls which model the in-session /model picker resolves the “Default” alias to. Without it, picking “Default” inside an interactive session jumps back to whatever Claude Code itself considers the current Opus.

Substitute any other published Opus version ID for 4.6 if you want to pin to something else (e.g. a dated revision). Remove the lines to return to the shipped defaults.

Dual Model System

Claude Code uses two models for optimal performance and cost:

1. Primary Model (`ANTHROPIC_MODEL`)

The main model you interact with. Set by your tier flags:

ai --opus task.md         # Uses CLAUDE_MODEL_OPUS_<PROVIDER>
ai --sonnet task.md       # Uses CLAUDE_MODEL_SONNET_<PROVIDER>
ai --haiku task.md        # Uses CLAUDE_MODEL_HAIKU_<PROVIDER>
ai --model custom-id      # Uses custom-id directly

Used for:

Main conversation
Complex reasoning
User-facing responses

2. Small/Fast Model (`ANTHROPIC_SMALL_FAST_MODEL`)

The background/auxiliary model for lightweight operations. Automatically set based on provider:

# From config/models.sh defaults:
export CLAUDE_SMALL_FAST_MODEL_AWS="${CLAUDE_MODEL_HAIKU_AWS}"
export CLAUDE_SMALL_FAST_MODEL_VERTEX="${CLAUDE_MODEL_HAIKU_VERTEX}"
export CLAUDE_SMALL_FAST_MODEL_ANTHROPIC="${CLAUDE_MODEL_HAIKU_ANTHROPIC}"
# ... etc for each provider

Used for:

Sub-agents and teammates (with --team)
File operations and analysis
Quick auxiliary tasks
Background work that doesn’t need the full model

Cost savings: Using Haiku for background operations while running Opus for main work reduces costs without sacrificing quality for complex reasoning.

How It’s Applied

When you run ai --aws --opus, the scripts set:

export ANTHROPIC_MODEL="global.anthropic.claude-opus-4-8"             # Primary
export ANTHROPIC_SMALL_FAST_MODEL="us.anthropic.claude-haiku-4-5-..." # Background

Claude Code automatically uses the appropriate model for each operation.

Overriding the Small/Fast Model

Customize in ~/.ai-runner/secrets.sh:

# Use Sonnet instead of Haiku for background work
export CLAUDE_SMALL_FAST_MODEL_AWS="global.anthropic.claude-sonnet-4-6"

# Use same model for both (consistency over cost)
export CLAUDE_SMALL_FAST_MODEL_AWS="${CLAUDE_MODEL_OPUS_AWS}"

When to override:

Agent teams: Higher-quality teammates with --team
Complex file operations: Better analysis with Sonnet background model
Consistency: Same model for all operations (disable two-model system)

Persistent Defaults

Save your preferred provider and model combination:

# Set default
ai --aws --opus --set-default

# Now 'ai' uses AWS + Opus by default
ai                        # Uses saved defaults
ai task.md                # Uses saved defaults

# Override saved defaults
ai --vertex task.md       # Uses Vertex instead
ai --haiku task.md        # Uses Haiku instead

# Clear saved defaults
ai --clear-default

What gets saved (~/.ai-runner/defaults.sh):

AI_DEFAULT_PROVIDER="aws"
AI_DEFAULT_MODEL_TIER="high"           # From --opus
AI_DEFAULT_CUSTOM_MODEL=""             # From --model (if used)
AI_DEFAULT_TOOL="codex"                # From --codex (if used)
AI_DEFAULT_EFFORT="high"               # From --effort (if used)
AI_DEFAULT_TEAM_MODE="enabled"         # From --team (if used)
AI_DEFAULT_TEAMMATE_MODE="tmux"        # From --teammate-mode (if used)

Precedence (highest to lowest):

CLI flags: ai --vertex task.md
Shebang flags: #!/usr/bin/env -S ai --aws
Saved defaults: --set-default
Auto-detection: Current Claude subscription

Model Configuration Files

`config/models.sh` (System Defaults)

Shipped with AI Runner, defines default model IDs for each provider:

# AWS Bedrock defaults
export CLAUDE_MODEL_SONNET_AWS="global.anthropic.claude-sonnet-4-6"
export CLAUDE_MODEL_OPUS_AWS="global.anthropic.claude-opus-4-8"
export CLAUDE_MODEL_HAIKU_AWS="us.anthropic.claude-haiku-4-5-20251001-v1:0"

# Small/fast model defaults
export CLAUDE_SMALL_FAST_MODEL_AWS="${CLAUDE_MODEL_HAIKU_AWS}"

These ship with AI Runner and are updated when new model versions are released.

`~/.ai-runner/models.sh` (User Copy)

Copied from config/models.sh during setup.sh. Updated when system defaults change:

./setup.sh
# Model configuration has been updated.
#   Changes include updated default model versions.
# Update to latest model defaults? [Y/n]:

When to update:

After git pull if model defaults changed
To get new model versions (e.g., Opus 4.8 → a newer Opus release)
If your models aren’t working (outdated IDs)

When to keep:

You have custom overrides in secrets.sh (they take precedence)
You want to pin specific versions

Override Hierarchy

secrets.sh overrides         ← Highest priority (user customization)
    ↓
~/.ai-runner/models.sh       ← Middle (user's copy of defaults)
    ↓
config/models.sh             ← Lowest (system defaults, read-only)

Example:

# config/models.sh (system default)
export CLAUDE_MODEL_OPUS_AWS="global.anthropic.claude-opus-4-8"

# User runs: ai --aws --opus
# Uses: global.anthropic.claude-opus-4-8

# User pins an older version in secrets.sh:
export CLAUDE_MODEL_OPUS_AWS="global.anthropic.claude-opus-4-6-v1"

# Now: ai --aws --opus
# Uses: global.anthropic.claude-opus-4-6-v1 (override wins)

Version File and Update Checking

AI Runner includes automatic update checking with smart caching.

Version File (`VERSION`)

Shipped with AI Runner, defines the current version:

cat VERSION
# v2.1.0

References:

Installed to: /usr/local/share/ai-runner/VERSION
Used by: ai --version, ai-status, update checker

Update Checking

AI Runner checks for updates once every 24 hours (non-blocking):

ai                # Shows update notice if available
ai-status         # Shows update status

How it works:

Cache-only check (runs in background on startup):
- Queries GitHub API for latest release
- Compares with installed version
- Caches result for 24 hours
- Never blocks startup

Notice display (if update available):

[AI Runner] Update available: v2.1.0 → v2.2.0
[AI Runner] Run 'ai update' to upgrade

Manual update:

ai update
# Fetching latest version from andisearch/airun...
# Current: v2.1.0
# Latest: v2.2.0
# Update available. Proceed? [Y/n]:

Disabling Update Checks

Add to your shell profile:

export AI_NO_UPDATE_CHECK=1

Reload:

source ~/.bashrc   # or ~/.zshrc

Update Cache Location

Update check results are cached at:

~/.ai-runner/.update-cache

Cache format:

cat ~/.ai-runner/.update-cache
# LAST_CHECK=1735689600
# LATEST_VERSION=v2.2.0
# UPDATE_AVAILABLE=true

Cache expires after 24 hours (86400 seconds).

Manual Update (Without `ai update`)

If you prefer manual updates:

cd ~/path/to/airun   # Your cloned repo
git pull
./setup.sh

This preserves your secrets.sh and prompts about updating models.sh.

Environment Variables Reference

Runtime Variables (Set by AI Runner)

Variable	Purpose	Set By
`ANTHROPIC_MODEL`	Primary model for main work	Provider scripts based on `--opus`/`--sonnet`/`--haiku`/`--model`
`ANTHROPIC_SMALL_FAST_MODEL`	Background/auxiliary model	Provider scripts from `CLAUDE_SMALL_FAST_MODEL_<PROVIDER>`
`ANTHROPIC_BASE_URL`	API endpoint	Provider scripts (Ollama, LM Studio, Vercel)
`ANTHROPIC_AUTH_TOKEN`	Bearer token auth	Provider scripts (Vercel)
`CLAUDE_CODE_USE_BEDROCK`	Enable AWS Bedrock mode	AWS provider
`CLAUDE_CODE_USE_VERTEX`	Enable Vertex AI mode	Vertex provider
`CLAUDE_CODE_USE_FOUNDRY`	Enable Azure Foundry mode	Azure provider
`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`	Enable agent teams	`--team` flag
`AI_LIVE_OUTPUT`	Enable live streaming	`--live` flag
`AI_QUIET`	Suppress narration	`--quiet` flag
`EFFORT_LEVEL`	Reasoning effort level	`--effort` flag
`AI_SESSION_ID`	Unique session identifier	Generated per session

User Configuration Variables (Set in secrets.sh)

Variable	Purpose	Example
`ANTHROPIC_API_KEY`	Anthropic API key	`sk-ant-...`
`AWS_PROFILE`	AWS credentials profile	`my-profile`
`AWS_REGION`	AWS region	`us-west-2`
`ANTHROPIC_VERTEX_PROJECT_ID`	GCP project ID	`my-project-123`
`CLOUD_ML_REGION`	Vertex AI region	`global`
`VERCEL_AI_GATEWAY_TOKEN`	Vercel gateway token	`vck_...`
`ANTHROPIC_FOUNDRY_API_KEY`	Azure API key	`your-key`
`ANTHROPIC_FOUNDRY_RESOURCE`	Azure resource name	`your-resource`
`CLAUDE_MODEL_<TIER>_<PROVIDER>`	Model override	`CLAUDE_MODEL_OPUS_AWS="..."`
`CLAUDE_SMALL_FAST_MODEL_<PROVIDER>`	Background model override	`CLAUDE_SMALL_FAST_MODEL_AWS="..."`
`AI_NO_UPDATE_CHECK`	Disable update checking	`1`

Troubleshooting Configuration

Check Current Configuration

ai-status

Shows:

Active provider
Authentication method
Primary model
Small/fast model
Agent teams status
Update availability

View Effective Model IDs

# In an active session
ai --aws --opus
# > /status
# Shows actual ANTHROPIC_MODEL value

Reset to System Defaults

# Remove user overrides
nano ~/.ai-runner/secrets.sh
# (delete CLAUDE_MODEL_* exports)

# Reset models.sh to system defaults
cd ~/path/to/airun
cp config/models.sh ~/.ai-runner/models.sh

Verify Override Hierarchy

# Check system default
grep CLAUDE_MODEL_OPUS_AWS ~/path/to/airun/config/models.sh

# Check user copy
grep CLAUDE_MODEL_OPUS_AWS ~/.ai-runner/models.sh

# Check user override
grep CLAUDE_MODEL_OPUS_AWS ~/.ai-runner/secrets.sh

# Highest non-empty value wins

Provider Setup — Authentication and credentials
Agent Teams — Multi-agent collaboration
Scripting Guide — Executable markdown and automation

​Configuration Files

​Model Overrides in secrets.sh

​AWS Bedrock

​Google Vertex AI

​Anthropic API

​Microsoft Azure

​Vercel AI Gateway

​Ollama (Local + Cloud)

​LM Studio (Local)

​Codex CLI

​Pinning Opus to a specific version

​Dual Model System

​1. Primary Model (ANTHROPIC_MODEL)

​2. Small/Fast Model (ANTHROPIC_SMALL_FAST_MODEL)

​How It’s Applied

​Overriding the Small/Fast Model

​Persistent Defaults

​Model Configuration Files

​config/models.sh (System Defaults)

​~/.ai-runner/models.sh (User Copy)

​Override Hierarchy

​Version File and Update Checking

​Version File (VERSION)

​Update Checking

​Disabling Update Checks

​Update Cache Location

​Manual Update (Without ai update)

​Environment Variables Reference

​Runtime Variables (Set by AI Runner)

​User Configuration Variables (Set in secrets.sh)

​Troubleshooting Configuration

​Check Current Configuration

​View Effective Model IDs

​Reset to System Defaults

​Verify Override Hierarchy

​Related Documentation