Andi AIRun

Run AI prompts like programs. Executable markdown with shebang, Unix pipes, and output redirection. Supports multiple runtimes (Claude Code, Codex CLI) with cross-cloud provider switching and any-model support — free local or 100+ cloud models.

# Claude Code: any model or provider
ai                                        # Regular Claude subscription (Pro, Max)
ai --aws --opus --team --resume           # Resume chats on AWS w/ Opus 4.8 + Agent Teams
ai --ollama --bypass --model qwen3-coder  # Ollama local model with bypassPermissions set

# Codex CLI: OpenAI's coding agent
ai --codex                                # Codex with gpt-5.4 (default)
ai --codex --high                         # Codex with gpt-5.4 (flagship)
ai --codex --ollama                       # Codex with local Ollama models

# Run prompts like programs (works with any runtime)
ai --azure --haiku script.md
ai --codex script.md

# Script automation
cat data.json | ./analyze.md > results.txt

Choose your runtime — Claude Code or Codex CLI — and switch between clouds + models: AWS Bedrock, Google Vertex, Azure, Vercel, Anthropic API, OpenAI API. Supports free local models (Ollama, LM Studio) and 100+ alternate cloud models via Vercel AI Gateway or Ollama Cloud. Swap and resume conversations mid-task to avoid rate limits and keep working.

What it does:

Multiple runtimes: Claude Code and Codex CLI with a single ai command (--cc, --codex)
Executable markdown with #!/usr/bin/env ai shebang for script automation
Unix pipe support: pipe data into scripts, redirect output, chain in pipelines
Cross-cloud provider switching: use Claude on AWS, Vertex, Azure, Anthropic API, or Codex on OpenAI, Azure OpenAI, OpenRouter + switch mid-conversation to bypass rate limits
Model tiers: --fable/--best (Claude Fable 5, top tier, Anthropic only), --opus/--high, --sonnet/--mid, --haiku/--low — maps to each runtime's models
Cross-interpreter effort control: --effort low|medium|high|max
Session continuity: --resume picks up your previous chats with any model/provider
Non-destructive: plain claude and codex always work untouched as before

From Andi AI Search. Star this repo if it helps!

Latest: Opus 4.8 default across all providers. Codex CLI support (--codex), cross-interpreter effort levels (--effort), tool profiles (--profile). Script variables, live streaming, Agent Teams, local models (Ollama, LM Studio), persistent defaults, 100+ cloud models via Vercel. See CHANGELOG.md.

Quick Start

Supported Platforms:

macOS 13.0+
Linux (Ubuntu 20.04+, Debian 10+)
Windows 10+ via WSL

Prerequisites: At least one runtime installed — Claude Code or Codex CLI

# Install a runtime (one or both)
curl -fsSL https://claude.ai/install.sh | bash   # Claude Code (Anthropic)
npm install -g @openai/codex                      # Codex CLI (OpenAI)

# Install Andi AIRun
git clone https://github.com/andisearch/airun.git
cd airun && ./setup.sh

You can now run any markdown file as an AI script:

# Create an executable prompt
cat > task.md << 'EOF'
#!/usr/bin/env ai
Analyze my codebase and summarize the architecture.
EOF

chmod +x task.md
./task.md                         # Runs with your Claude subscription

Or run any markdown file directly:

ai task.md

Pipe data and redirect output (Unix-style automation):

cat data.json | ./analyze.md > results.txt    # Pipe in, redirect out
git log -10 | ./summarize.md                  # Feed git history to AI
./generate.md | ./review.md > final.txt       # Chain scripts together

Run scripts from the web (installmd.org support):

curl -fsSL https://andisearch.github.io/ai-scripts/analyze.md | ai
echo "Explain what a Makefile does" | ai         # Simple prompt

Minimal alternative: If you just want basic executable markdown without installing this repo, add a ai script to your PATH:

#!/bin/bash
claude -p "$(tail -n +2 "$1")"

This works for simple prompts but lacks provider switching, model selection, stdin piping, output formats, and session isolation. (credit: apf6)

Commands

Command	Description
`ai` / `airun`	Universal entry point - run scripts, switch providers
`ai update`	Update AI Runner to the latest version
`ai-sessions`	View active AI coding sessions
`ai-status`	Show current configuration and provider status

Running ai with no flags matches your claude defaults — if you're logged in with a subscription, ai uses it. Your environment is automatically restored on exit. Add provider flags to switch, or use ai --aws --opus --set-default to save your preferred provider and model for future runs.

Usage Examples

# Run a markdown script (auto-detects runtime + provider)
ai task.md

# Choose your runtime
ai --cc                           # Claude Code (default if installed)
ai --codex                        # Codex CLI (OpenAI)

# Claude Code providers
ai --aws                          # AWS Bedrock
ai --vertex                       # Google Vertex AI
ai --apikey                       # Anthropic API
ai --azure                        # Microsoft Azure Foundry
ai --vercel                       # Vercel AI Gateway
ai --pro                          # Claude Pro/Max subscription

# Codex CLI providers
ai --codex                        # OpenAI API (default)
ai --codex --azure                # Azure OpenAI (via config.toml)
ai --codex --profile openrouter   # OpenRouter (via config.toml profile)

# Local models (work with both runtimes)
ai --ollama                       # Ollama with Claude Code
ai --codex --ollama               # Ollama with Codex CLI
ai --lmstudio                     # LM Studio (MLX, Apple Silicon)

# Model tiers (map to each runtime's best models)
ai --fable task.md                # Claude: Fable 5 (top tier, Anthropic only); --best is a synonym
ai --opus task.md                 # Claude: Opus 4.8 (default) / Codex: gpt-5.4
ai --sonnet task.md               # Claude: Sonnet 4.6 / Codex: gpt-5.3-codex (mid tier)
ai --haiku task.md                # Claude: Haiku 4.5 / Codex: gpt-5.4-mini
ai --codex --high task.md         # Codex with gpt-5.4

# Effort level (cross-interpreter reasoning control)
ai --effort high task.md          # Claude Code: deeper reasoning
ai --codex --effort max task.md   # Codex: maximum reasoning (xhigh)

# Stream output in real-time
ai --live --skip task.md

# Suppress --live status for CI/CD (clean stdout only)
ai --quiet ./live-script.md > output.md

# Live output + file redirect (narration to console, clean content to file)
./live-report.md > report.md

# Override script variables (--topic, --style match declared vars: names)
./summarize-topic.md --live --topic "the fall of rome" --style "peter griffin"

# Resume last conversation
ai --aws --resume

# Save runtime + provider + model as default
ai --codex --high --set-default   # Always use Codex + gpt-5.4
ai --aws --opus --set-default     # Always use Claude Code + AWS + Opus
ai --clear-default                # Remove saved default

# Smart auto permissions (AI classifier for Claude Code, sandbox for Codex)
ai --auto task.md

# Enable agent teams (Claude Code, experimental, interactive only)
ai --team                         # Auto display mode
ai --aws --opus --team            # Teams with AWS Bedrock + Opus

Features

Executable Markdown

Create markdown files with prompts that run directly via shebang:

#!/usr/bin/env ai
Summarize the architecture of this codebase.

#!/usr/bin/env -S ai --aws
Use AWS Bedrock to analyze this code.

#!/usr/bin/env -S ai --codex --high
Use Codex CLI with the flagship model to review this code.

#!/usr/bin/env -S ai --opus --live
Review this PR for security issues. Stream output in real-time.

Scripts that write files or run commands need a permission mode:

#!/usr/bin/env -S ai --skip
Run ./test/automation/run_tests.sh and report results.

(--skip is a shortcut for --dangerously-skip-permissions. See also --bypass for --permission-mode bypassPermissions.)

#!/usr/bin/env -S ai --auto
Run tests and fix any issues found.

(--auto uses an AI classifier (Claude Code) or sandbox (Codex) to auto-approve safe actions.)

#!/usr/bin/env -S ai --allowedTools 'Bash(npm test)' 'Read'
Run the test suite and report results. Do not modify any files.

(--allowedTools is a Claude Code flag, passed through by AI Runner.)

Usage:

chmod +x task.md
./task.md                          # Execute directly (uses shebang flags)
ai --vercel task.md                # Override: use Vercel instead
ai --opus task.md                  # Override: use Opus instead

Tip: Use #!/usr/bin/env -S (with -S) to pass flags in the shebang line. Standard env only accepts one argument, so #!/usr/bin/env ai --aws won't work — you need -S to split the string.

Flag precedence: CLI flags > shebang flags > saved defaults. Running ai --vercel task.md overrides the script's shebang provider. Shebang flags override --set-default preferences.

Passthrough flags: AI Runner handles its own flags (provider, model, --live, --quiet, --skip, --bypass, --auto, --team, etc.) and forwards any unrecognized flags (e.g. --chrome, --allowedTools, --output-format, --verbose) to the underlying Claude Code process unchanged.

Portability: Scripts are portable across runtimes. If a script includes interpreter-specific flags (e.g., --chrome for Claude Code), running it on another runtime produces a warning but continues execution.

Warning: --skip, --bypass, and --permission-mode bypassPermissions give the AI full system access. Only run trusted scripts in trusted directories. Use --allowedTools for granular control. See docs/SCRIPTING.md for details.

See examples/ for ready-to-run scripts and docs/SCRIPTING.md for the full scripting & automation guide.

Script Variables

Declare variables with defaults in YAML front-matter. Users override them from the CLI without editing the script:

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

./summarize-topic.md                          # uses defaults
./summarize-topic.md --topic "AI safety"      # overrides one
./summarize-topic.md --topic "robotics" --style formal  # overrides two

Boolean flags — --varname without a value sets the variable to "true":

# Given a script with vars: verbose: false
./script.md --verbose                         # sets verbose to "true"
./script.md --verbose --topic "AI safety"     # verbose="true", topic overridden

Variable overrides mix freely with AI Runner flags like --live and provider overrides:

./summarize-topic.md --live --length "100 words" --topic "the fall of rome" --style "peter griffin"
ai --aws --opus summarize-topic.md --topic "quantum computing"

Override flags matching declared var names are consumed — --live, --aws, and other unrecognized flags still pass through. Hyphens normalize to underscores (--brief-only matches brief_only). Only activates when front-matter contains vars: — no behavior change for existing scripts.

Unix Pipe Support

Executable markdown scripts have proper Unix semantics for automation:

Clean piped output - when you redirect to a file, you get only the AI's response
Stdin support - pipe data directly into scripts
Chainable - connect scripts together in pipelines
Standard streams - stdout is data, stderr is diagnostics

# Clean output to file
./analyze.md > results.txt

# Pipe data into scripts
cat data.json | ./process.md
git log --oneline -20 | ./summarize-changes.md

# Chain scripts together
./generate-report.md | ./format-output.md > final.txt

# Control stdin position (default: prepend)
cat data.txt | ./analyze.md --stdin-position append

Use in shell scripts:

#!/bin/bash
for f in logs/*.txt; do
    cat "$f" | ./analyze.md >> summary.txt
done

Composable scripts: AIRun clears inherited environment variables between nested calls, so chained scripts each start fresh. See docs/SCRIPTING.md for composable patterns, the dispatcher pattern (--cc --skip), and long-running script tips.

Piped Script Execution

Run AI scripts directly from the web:

# Run a script from the web
curl -fsSL https://andisearch.github.io/ai-scripts/analyze.md | ai

# Simple prompt via pipe
echo "Explain what a Dockerfile does" | ai

# Override provider from shebang
curl -fsSL https://example.com/script.md | ai --aws

Agent Teams (Experimental)

Enable Claude Code's agent teams — multiple Claude instances collaborating on shared tasks with one session as lead coordinating teammates.

ai --team                        # Enable agent teams
ai --aws --opus --team           # Combine with any provider
ai --team --teammate-mode tmux   # Split panes via tmux

Flag	Purpose
`--team`	AI Runner flag — enables agent teams by setting `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
`--teammate-mode <mode>`	Claude Code native flag — controls display: `in-process`, `tmux`, or `auto` (default)

Interactive mode only (not supported in shebang/piped script modes)
Works with all providers — coordination is through Claude Code's internal task list, not provider-specific
Token usage scales with team size (5 teammates ≈ 5× tokens)

Runtimes and Providers

Runtimes

Flag	Runtime	Default Model	Install
`--cc`	Claude Code	claude-opus-4-8	`curl -fsSL https://claude.ai/install.sh \| bash`
`--codex`	Codex CLI	gpt-5.4	`npm install -g @openai/codex`

Claude Code is the default runtime when both are installed. If only Codex is installed, it becomes the default automatically.

Providers

Flag	Provider	Claude Code	Codex CLI	Type
`--ollama` / `--ol`	Ollama	Yes	Yes	Local
`--lmstudio` / `--lm`	LM Studio	Yes	Yes	Local
`--aws`	AWS Bedrock	Yes	—	Cloud
`--vertex`	Google Vertex AI	Yes	—	Cloud
`--apikey`	Anthropic / OpenAI API	Yes	Yes	Cloud
`--azure`	Azure Foundry / Azure OpenAI	Yes	Yes	Cloud
`--vercel`	Vercel AI Gateway	Yes	—	Cloud
`--pro`	Claude Pro	Yes	—	Subscription
`--profile <name>`	Config profile	—	Yes	Any

Codex custom providers (OpenRouter, Mistral, DeepSeek, etc.) are configured in ~/.codex/config.toml and selected with --profile <name>. See the Codex CLI docs for config.toml setup.

Quick Start Examples

# Local providers (free, no API costs — work with both runtimes)
ai --ollama                    # Claude Code + Ollama
ai --codex --ollama            # Codex CLI + Ollama

# Claude Code cloud providers
ai --aws --opus task.md        # AWS Bedrock + Opus 4.8
ai --vertex task.md            # Google Vertex AI

# Codex CLI cloud providers
ai --codex task.md             # OpenAI API + gpt-5.4
ai --codex --azure task.md     # Azure OpenAI (config.toml)

Provider Setup

Local Providers (Free, No API Keys)

Hardware note: Coding models need 24GB+ VRAM (or unified memory on Apple Silicon). Ollama's cloud models work on any hardware.

Ollama — runs models locally or on Ollama's cloud:

# Install Ollama
brew install ollama                   # macOS
curl -fsSL https://ollama.com/install.sh | sh  # Linux / WSL

# Quick setup (Ollama 0.15+)
ollama launch claude                  # Auto-configure and launch Claude Code

# Or manual setup
ollama pull qwen3-coder               # Pull a model (needs 24GB+ VRAM)
ai --ollama                           # Run with Ollama

# Cloud models — no GPU required, runs on Ollama's servers
ollama pull minimax-m2.5:cloud        # Best coding (80% SWE-bench, MIT)
ollama pull glm-5:cloud               # Best reasoning (78% SWE-bench, MIT)
ai --ollama --model minimax-m2.5:cloud

LM Studio — local models with MLX support (fast on latest Apple Silicon):

# 1. Download from lmstudio.ai and load a model
# 2. Start the server: lms server start --port 1234
ai --lm                               # Run with LM Studio

See docs/PROVIDERS.md for model recommendations, configuration, and auto-download features.

Cloud Providers

Add your credentials to ~/.ai-runner/secrets.sh (created by ./setup.sh). Andi AIRun loads this file automatically, so you don't need to set environment variables in your shell profile.

nano ~/.ai-runner/secrets.sh

Uncomment and fill in what you have:

# Anthropic API
export ANTHROPIC_API_KEY="sk-ant-..."

# AWS Bedrock
export AWS_PROFILE="your-profile-name"
export AWS_REGION="us-west-2"

# Google Vertex AI
export ANTHROPIC_VERTEX_PROJECT_ID="your-gcp-project-id"
export CLOUD_ML_REGION="global"

# Vercel AI Gateway
export VERCEL_AI_GATEWAY_TOKEN="vck_..."

# Microsoft Azure
export ANTHROPIC_FOUNDRY_API_KEY="your-azure-api-key"
export ANTHROPIC_FOUNDRY_RESOURCE="your-resource-name"

You only need to configure the providers you want to use. See docs/PROVIDERS.md for all authentication options and detailed setup instructions.

Switching Providers to Avoid Rate Limits

Claude Pro has rate limits. When you hit a limit mid-task, switch to your API keys and keep working.

# Working with Claude Pro, hit rate limit
claude
# "Rate limit exceeded. Try again in 4 hours 23 minutes."

# Immediately continue with AWS (keeps conversation context)
ai --aws --resume

# Or switch to Haiku for speed/cost, Opus for complex reasoning
ai --aws --haiku --resume
ai --aws --opus --resume

# Or use local Ollama (free!)
ai --ollama --resume

The --resume flag lets you pick up a previous conversation exactly where you left off.

Installation

Setup

git clone https://github.com/andisearch/airun.git
cd airun
./setup.sh

The setup script installs commands to /usr/local/bin, creates ~/.ai-runner/ for configuration, and migrates any existing ~/.claude-switcher/ configuration.

Note: Setup does NOT modify your Claude configuration. All scripts are session-scoped and automatically restore your original configuration on exit.

Updating

ai update

Or manually: cd airun && git pull && ./setup.sh

AI Runner checks for updates once every 24 hours (non-blocking, cache-only) and shows a notice in interactive mode and ai-status when a new version is available. Disable with export AI_NO_UPDATE_CHECK=1.

Your API keys in ~/.ai-runner/secrets.sh are preserved.

Updating from claude-switcher

If you have the original claude-switcher installed, just pull and re-run setup:

cd claude-switcher && git pull && ./setup.sh

GitHub's redirect ensures git operations continue working with the old remote URL.

What happens automatically:

Your ~/.claude-switcher/secrets.sh is migrated to ~/.ai-runner/secrets.sh
All legacy claude-* commands continue to work (see Backward Compatibility)
Existing #!/usr/bin/env claude-run shebangs still work

Optional cleanup:

# Rename local directory
cd .. && mv claude-switcher airun && cd airun

# Update remote to canonical URL
git remote set-url origin https://github.com/andisearch/airun.git

New commands: ai / airun replace claude-run as the primary entry point.

Uninstallation

./uninstall.sh

Backward Compatibility

All legacy claude-* commands continue to work unchanged:

Legacy Command	Equivalent
`claude-run`	`ai`
`claude-aws`	`ai --aws`
`claude-vertex`	`ai --vertex`
`claude-apikey`	`ai --apikey`
`claude-azure`	`ai --azure`
`claude-vercel`	`ai --vercel`
`claude-pro`	`ai --pro`
`claude-status`	`ai-status`
`claude-sessions`	`ai-sessions`

Existing shebang scripts with #!/usr/bin/env claude-run still work.

Configuration in ~/.claude-switcher/ is automatically migrated to ~/.ai-runner/.

Configuration

Models

Default model IDs are defined in config/models.sh. Override them in ~/.ai-runner/secrets.sh:

# Override Claude Code AWS model
export CLAUDE_MODEL_SONNET_AWS="global.anthropic.claude-sonnet-4-6"

# Override Codex model tiers
export CODEX_MODEL_HIGH="gpt-5.4"
export CODEX_MODEL_MID="gpt-5.3-codex"
export CODEX_MODEL_LOW="gpt-5.4-mini"

# Save preferred runtime + provider + model as default
ai --codex --high --set-default
ai --aws --opus --set-default
ai --clear-default              # Remove saved default

Dual Model Configuration

Claude Code uses two models:

ANTHROPIC_MODEL - Main model for interactive work
ANTHROPIC_SMALL_FAST_MODEL - Background operations (defaults to Haiku)

Troubleshooting

Verify Configuration

ai-status                              # Shows authentication and configuration

Common Issues

Still getting rate limits after switching to API?

Verify API key: grep ANTHROPIC_API_KEY ~/.ai-runner/secrets.sh
Confirm you're using ai (not plain claude)
Run ai-status during the session
In Claude, run /status to see authentication method

Switching back to Pro not working?

Use ai --pro or plain claude
Run /status in Claude to verify authentication

Want to pin to a specific Opus version (e.g. 4.6)?

Whether you prefer an older release for personal-preference reasons, hit a transient provider bug with the latest one, or want to avoid a known regression in your workload, you can pin Opus across all providers in ~/.ai-runner/secrets.sh:

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 the in-session /model picker's "Default" alias.
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6"

See Pinning Opus to a specific version for the full explanation.

Session-Scoped Behavior

ai with no flags matches your claude defaults — subscription if logged in, API key if configured. Provider flags (--aws, --ollama, etc.) only affect the current session:

On exit, your original Claude settings are automatically restored
Plain claude in another terminal is completely unaffected
No global configuration is changed

Versioning

Current Version: see VERSION or run ai --version

This project follows Semantic Versioning. See CHANGELOG.md for version history.

Name History

Originally named claude-switcher, renamed to Andi AIRun in 2026. Previous URLs (github.com/andisearch/claude-switcher) redirect here automatically. Legacy configuration (~/.claude-switcher/) is still supported.

Support

Andi AIRun is free and open source.

Star on GitHub - helps others discover the project
Buy Me a Coffee - one-time support
GitHub Sponsors - supports Andi AI search

Acknowledgments

Thanks to Pete Koomen from YC for the great idea of executable markdown! Pete's insight: executable prompts become reusable tools. Put them in your repo. Run them in CI. Chain them together.

Thanks to Reddit user apf6 for the suggestion to add a minimal alternative script for shebang support.

Thanks to the team at Anthropic for Claude Code and the fantastic Claude models. We are not associated with Anthropic.

Thanks to the Startups teams at Microsoft Azure, AWS and Google Cloud for their support.

Authors

Andi AIRun is created and maintained by:

Jed White, CTO of Andi
Angela Hoover, CEO of Andi

Contributions welcome. See CONTRIBUTORS.md.

License

See LICENSE for full license text.

Name		Name	Last commit message	Last commit date
Latest commit History 117 Commits
.github		.github
config		config
docs		docs
examples		examples
providers		providers
scripts		scripts
test		test
tools		tools
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTORS.md		CONTRIBUTORS.md
LICENSE		LICENSE
README.md		README.md
VERSION		VERSION
secrets.example.sh		secrets.example.sh
setup.sh		setup.sh
shebang-example.md		shebang-example.md
uninstall.sh		uninstall.sh
verify_env.sh		verify_env.sh

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Andi AIRun

Quick Start

Commands

Usage Examples

Features

Executable Markdown

Script Variables

Unix Pipe Support

Piped Script Execution

Agent Teams (Experimental)

Runtimes and Providers

Runtimes

Providers

Quick Start Examples

Provider Setup

Local Providers (Free, No API Keys)

Cloud Providers

Switching Providers to Avoid Rate Limits

Installation

Setup

Updating

Updating from claude-switcher

Uninstallation

Backward Compatibility

Configuration

Models

Dual Model Configuration

Troubleshooting

Verify Configuration

Common Issues

Session-Scoped Behavior

Versioning

Name History

Support

Acknowledgments

Authors

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages