Multi-Model Workflows

Aider is model-agnostic. It works with Claude, GPT, Gemini, DeepSeek, and any OpenAI-compatible API, including local models through Ollama and LM Studio. The power is not just in picking one model. It is in switching models mid-session: a reasoning model for architecture, a fast model for simple edits, a cheap model for commit messages. This lesson covers model switching, persistent configuration, voice coding, and the --watch mode that turns your IDE into an Aider prompt.

What you'll learn

• /model <name> switches the main model mid-session without losing chat context
• /weak-model <name> switches the model used for commit messages and chat summarization
• .aider.conf.yml stores persistent configuration: default model, API keys, map tokens, edit formats
• Aider works with 20+ providers including OpenAI, Anthropic, Gemini, DeepSeek, Ollama, OpenRouter, and local models
• Voice coding with /voice and IDE integration with --watch extend Aider beyond the terminal prompt

The problem

No single model is best at everything. Reasoning models like o3 and o1 are excellent at complex design but slow and expensive. Fast models like GPT-4o and Claude Sonnet are great for everyday edits but can miss architectural implications. Cheap models like GPT-4o-mini and Haiku are perfect for commit messages. The best Aider workflow uses all three: reason with the smart model, edit with the fast model, and let the cheap model handle the bookkeeping. Switching models mid-session means you never have to choose one model for an entire task.

Options & when to use each

Model strategy	Command	When to use it
Single strong model	aider --model sonnet	Simple projects, consistent quality, minimal context switching
Reasoning + editor	aider --architect --model o3-mini --editor-model sonnet	Complex multi-file changes where design quality matters more than speed
Fast default, switch for hard problems	Start with gpt-4o, /model o3-mini for hard prompts	Day-to-day coding where 80% of prompts are simple
Cheap default, switch for quality	Start with gpt-4o-mini, /model sonnet for important changes	Cost-sensitive workflows, rapid prototyping
Local first, cloud for hard tasks	Start with ollama/llama3.1, /model sonnet when stuck	Privacy-sensitive projects, offline work
Dedicated weak model	/weak-model gpt-4o-mini	Saving costs on commit messages and summarization

Build it

Step 1: Understand Aider's model roles

Aider uses three model roles:

Role	Selected by	Purpose
Main model	--model or /model	Handles your prompts and produces code edits
Weak model	--weak-model or /weak-model	Generates commit messages and summarizes chat history
Editor model	--editor-model or /editor-model	In architect mode, translates architect proposals into file edits

The main model is the only one you directly interact with. The weak model runs in the background after every edit. The editor model runs only in architect mode.

Step 2: Switch models mid-session

Create a practice session:

cd ~/aider-practice
aider --model gpt-4o-mini app.py

Start with a cheap model for simple edits:

> Add a docstring to every function in app.py

Now switch to a stronger model for a harder task:

> /model sonnet

Aider switches the main model to Claude Sonnet. All previous chat context is preserved. The weak model and editor model are unchanged.

> Add input validation to all endpoints. Validate that required fields are present, types are correct, and values are within reasonable ranges. Add proper error responses.

The prompt now runs through Sonnet, which handles the complex validation logic better than GPT-4o-mini. After the task:

> /model gpt-4o-mini

Switch back to the cheaper model for routine edits. This pattern -- cheap for simple, strong for complex -- is the most cost-effective workflow.

Step 3: Configure the weak model

The weak model generates commit messages. You rarely think about it, but it runs after every edit. Switch it to something cheap:

> /weak-model gpt-4o-mini

Or set it at launch by passing both the primary and weak model flags. This configures the session to use the appropriate model for each task right from the start.

aider --model sonnet --weak-model gpt-4o-mini

The weak model also summarizes chat history when the context window fills up. A better weak model produces better summaries, but the cost adds up over long sessions. For most projects, gpt-4o-mini or haiku is the right balance.

Step 4: Create a persistent configuration

Stop passing flags on every launch. Create a .aider.conf.yml:

cat > ~/aider-practice/.aider.conf.yml << 'EOF'
# Default model for everyday coding
model: gpt-4o

# Cheap model for commit messages
weak-model: gpt-4o-mini

# Editor model for architect mode
editor-model: sonnet

# Repomap configuration
map-tokens: 2048

# Git configuration
auto-commits: true
attribute-author: true
attribute-committer: true

# Editor configuration
editor: vim

# Read project conventions file at startup
read:
  - CONVENTIONS.md
EOF

Aider loads .aider.conf.yml from three locations (in order of priority):

1. Home directory (~/.aider.conf.yml)
2. Git repo root
3. Current directory

Files loaded later override files loaded earlier. Put global defaults in your home directory and project overrides in the repo root.

You can also specify a config file explicitly:

aider --config ~/my-aider-config.yml

Step 5: Store API keys in .env

Never put API keys in .aider.conf.yml (except OpenAI and Anthropic keys, which it supports). Use a .env file at the repo root:

cat > ~/aider-practice/.env << 'EOF'
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=...
DEEPSEEK_API_KEY=...
EOF

Aider reads .env automatically. For extra security, use --env-file to point to a file outside the repo:

aider --env-file ~/.aider-env

Step 6: Use voice coding

Aider supports voice input with the /voice command. This requires portaudio libraries:

# Ubuntu/Debian
sudo apt install portaudio19-dev

# macOS
brew install portaudio

# Then install aider with voice support
pip install aider-chat[voice]

Inside Aider, trigger the voice recording command. Speak your prompt, and press enter when finished to let the system transcribe and process it.

> /voice
Recording, press ENTER when done... 3.2sec

"Add a function that validates email addresses using a regex"

Aider transcribes your speech and treats it exactly like typed input. The transcription is visible in the chat so you can verify it was correct.

Voice coding is useful when you want to describe a complex change without typing, or when you are thinking out loud about a design. Switch between voice and text freely in the same session.

Step 7: Integrate with your IDE via --watch

The --watch flag lets you use Aider from any text editor. Add AI comments to your files, save, and Aider processes them:

aider --watch --model sonnet

Now edit any file in your project and add an AI comment:

# AI: Add input validation to this endpoint
# AI: Check that name is non-empty, email matches a regex, and age is between 0 and 150

Save the file. Aider detects the change, reads the AI comments, and makes the edits. The workflow is:

1. You write # AI: <what you want> in your IDE
2. You save the file
3. Aider reads the comment, makes the edit, commits
4. You see the result in your IDE

This combines Aider's git-first approach with the comfort of your existing editor. No more context switching between terminal and IDE.

You can also combine --watch with --model and --editor-model:

aider --watch --model sonnet --editor-model gpt-4o

Step 8: Run multiple provider configurations

Aider supports 20+ providers. Here is how to configure the most common ones:

# Anthropic Claude
export ANTHROPIC_API_KEY=sk-ant-...
aider --model sonnet

# OpenAI
export OPENAI_API_KEY=sk-...
aider --model gpt-4o

# Google Gemini
export GEMINI_API_KEY=...
aider --model gemini/gemini-2.5-pro

# DeepSeek
export DEEPSEEK_API_KEY=...
aider --model deepseek

# OpenRouter (access many models through one API)
export OPENROUTER_API_KEY=...
aider --model openrouter/anthropic/claude-sonnet-4

# Ollama (local models)
aider --model ollama/llama3.1

# LM Studio (local models)
aider --model openai/lmstudio-community/Meta-Llama-3.1-8B-Instruct

Set multiple keys in your .env file and switch providers with /model:

> /model sonnet
# Uses Anthropic

> /model gpt-4o
# Uses OpenAI

> /model gemini/gemini-2.5-pro
# Uses Google

All in one session, with full chat history preserved.

Step 9: Model aliases for convenience

Long model names are tedious. Create aliases in .aider.conf.yml:

alias:
  - "fast:gpt-4o-mini"
  - "smart:sonnet"
  - "reason:o3-mini"
  - "gemini:gemini/gemini-2.5-pro"
  - "local:ollama/llama3.1"

Now switch with short names:

> /model smart
> /model fast
> /model reason

This makes the cheap-for-simple, strong-for-complex workflow frictionless.

What goes wrong

Mistake	How you notice it	The fix
Switching models loses context	The new model seems unaware of earlier conversation	Model switching preserves the full chat history. If the new model seems confused, the context window may have been full. Use /clear before switching or summarize with /drop unused files
Weak model produces bad commit messages	Commit messages are generic or wrong	Switch to a better weak model: /weak-model haiku or /weak-model gpt-4o-mini. Or disable automatic commit messages and use /commit manually
Voice recording fails silently	/voice starts but produces no transcription	Install portaudio: sudo apt install portaudio19-dev. Check your microphone works with arecord -d 3 test.wav. Verify the audio format: --voice-format wav
AI comments in --watch mode are not detected	Aider does not respond to # AI: comments	Aider watches for changes in git-tracked files. The file must be saved after you add the comment. Check that --watch-files is enabled (it is on by default with --watch)
Local model via Ollama produces garbled edits	Edits fail to apply or produce nonsensical code	Local models are weaker than cloud models at code editing. Use --edit-format whole for local models. Or reserve local models for ask-mode exploration and switch to a cloud model for editing
Mixing API keys from different providers causes confusion	Aider uses the wrong provider for the selected model	Each provider uses its own environment variable. Check that the right key is set. Use aider --model openai/gpt-4o (explicit provider prefix) to avoid ambiguity
.aider.conf.yml conflicts with command-line flags	Behavior does not match what you specified on the command line	Command-line flags override the config file. If both are set, the CLI wins. Check /settings to see the effective configuration

Confirm it worked

Run this sequence. If every step succeeds, you have mastered multi-model workflows:

# 1. Create a config file with aliases
cd ~/aider-practice

# 2. Launch with a cheap model
aider --model gpt-4o-mini app.py

# 3. Do a simple edit
> Add a comment at the top of app.py explaining what the file does

# 4. Switch to a strong model for a complex task
> /model sonnet
> Refactor the greeting endpoint to support multiple greeting styles (casual, formal, technical) 
selected via a query parameter. Add proper error handling for invalid styles.

# 5. Switch the weak model
> /weak-model gpt-4o-mini

# 6. Make another change and verify the commit message quality
> Add a /version endpoint that returns the app version from a VERSION constant

# 7. Check the commit messages
> /git log --oneline -5

# 8. Print current settings
> /settings

If the commit messages are descriptive, the model switches are seamless, and grep "casual\|formal\|technical" app.py shows the multi-style greeting implementation, your multi-model workflow is production-ready.

Next: Day 3 -- OpenHands: The Autonomous Agent Platform