Architect Mode

Architect mode separates planning from editing. Instead of asking one model to both design a solution and write the file edits, Aider uses two models: an architect that proposes what to build, and an editor that translates that proposal into precise code changes. This two-pass approach produces better results on complex tasks, especially when the architect is a strong reasoning model and the editor is a fast, code-editing specialist.

What you'll learn

• Architect mode uses two models: a main model to propose the solution (the architect) and an editor model to apply the edits
• Activate with --architect at launch, /architect for a single message, or /chat-mode architect to switch the session
• The /ask and /code workflow is a lighter alternative: discuss the plan in ask mode, then switch to code mode to execute
• Architect mode is especially effective with reasoning models (OpenAI o1, o3) as the architect paired with a code editor like GPT-4o or Claude Sonnet
• You can customize the editor model with --editor-model and its edit format with --editor-edit-format

The problem

When you give a complex task to a single model, it must simultaneously reason about architecture, API design, error handling, and precise file edits. Strong reasoning models like OpenAI o1 and o3 are excellent at designing solutions but weak at producing the exact search/replace blocks Aider needs to apply edits. Fast code editors like GPT-4o and Claude Sonnet are excellent at producing precise edits but can rush into implementation without thinking through the design. Architect mode gives you both: the reasoning model designs, the editing model implements.

Options & when to use each

Mode	Command	Good for	When to pick it
Code mode (default)	aider or /code	Straightforward edits, single-file changes, bug fixes	Your task is well-understood and the implementation is obvious
Ask mode	/ask	Questions, exploration, design discussions	You want to understand the codebase or brainstorm approaches before writing code
Architect mode	aider --architect	Complex multi-file changes, new features, refactors	The solution requires design thinking before implementation
One-shot architect	/architect <prompt>	A single complex task in an otherwise code-mode session	You have one architectural question but mostly simple edits
Ask-then-code workflow	/ask then /code	Fluid planning-then-execution with one model	You want the benefits of architect mode without the cost of two models

Architect mode costs two API calls per prompt instead of one. Use it when the quality improvement justifies the cost and latency. For trivial changes like renaming a variable or fixing a typo, code mode is faster and cheaper.

Build it

Step 1: Understand the two-pass flow

When you send a prompt in architect mode, here is what happens:

1. Pass 1 (architect): Your prompt is sent to the main model with instructions to propose a solution. The architect describes what to change, which files to touch, and the design reasoning. It does NOT produce file edits.

2. Pass 2 (editor): The architect's proposal is sent to the editor model with instructions to translate it into specific file edits. The editor produces search/replace blocks that Aider applies to the files.

The architect's proposal is visible to you in the chat. You can see the reasoning before the edits are applied. This transparency is part of the value: you understand why a change is being made, not just what changed.

Step 2: Launch in architect mode

Create a project that needs architectural thinking:

mkdir -p ~/aider-architect && cd ~/aider-architect && git init

Populate the project with a basic script that we can refactor. This script currently runs tasks sequentially and lacks proper error isolation.

cat > task_runner.py << 'EOF'
import subprocess
import json

def run_task(name):
    """Run a named task and return its output."""
    result = subprocess.run(["echo", f"Running {name}"], capture_output=True, text=True)
    return result.stdout.strip()

def run_all(tasks):
    """Run all tasks and return results."""
    results = {}
    for task in tasks:
        results[task] = run_task(task)
    return results

if __name__ == "__main__":
    tasks = ["build", "test", "deploy"]
    for task, result in run_all(tasks).items():
        print(f"{task}: {result}")
EOF

git add . && git commit -m "Initial task runner"

Now launch Aider in architect mode:

aider --architect --model o3-mini task_runner.py

You will see a startup banner confirming your dual-model configuration.

Aider v0.80.0
Model: openai/o3-mini with editor-diff edit format
Editor model: openai/gpt-4o
Git repo: .git with 1 files
Repo-map: using 1024 tokens
architect>

The architect> prompt confirms you are in architect mode. The startup banner shows both models: o3-mini as the architect and gpt-4o as the editor.

Step 3: Give a complex, architectural task

Ask for a non-trivial refactor:

architect> Refactor task_runner.py to support parallel task execution with a configurable concurrency limit. Add proper error handling: if a task fails, it should not block other tasks. Support both shell commands and Python callables as tasks. Keep backward compatibility with the existing run_task and run_all functions.

The architect (o3-mini) responds with a design proposal:

I'll refactor the task runner to support parallel execution. Here's my plan:

1. Add a Task type (Union[Callable, str]) to represent both Python callables and shell commands
2. Add a run_tasks_parallel function that uses concurrent.futures.ThreadPoolExecutor
3. Add a max_workers parameter with a sensible default (e.g., os.cpu_count())
4. Wrap each task execution in try/except to prevent failures from cascading
5. Keep run_task and run_all as thin wrappers that delegate to the new parallel implementation
6. Update the __main__ block to demonstrate parallel execution

Then the editor (GPT-4o) translates this into file edits. You see the plan first, then the implementation. If the plan looks wrong, you can redirect before any code is written:

architect> Instead of ThreadPoolExecutor, use asyncio for the parallel execution

The architect revises the plan, and the editor produces new edits.

Step 4: Use the lighter ask/code workflow

Architect mode is powerful but uses two models. For many tasks, the ask/code workflow with a single model gives similar benefits:

# Start in normal code mode
> /ask I need to add retry logic to the task runner. What's a good approach?

Aider enters ask mode and discusses approaches without editing files:

ask> For retry logic, you could:
1. Wrap the task execution in a loop with exponential backoff
2. Add a max_retries parameter to run_task
3. Use a decorator pattern for reusable retry behavior
4. Or add it to the parallel runner so all tasks get retries automatically

Which approach fits your use case?

Select the preferred approach and respond to the agent.

ask> Let's go with option 4 -- retries in the parallel runner. Max 3 retries with exponential backoff.

Once the approach is settled, transition to code mode to execute the changes.

ask> /code Go ahead

Aider switches to code mode and implements the agreed-upon design. The entire design discussion happened without a single file change, and the implementation was a single terse prompt.

Step 5: Customize the editor model

By default, Aider picks an editor model based on your main model. You can override this:

# Use Claude Sonnet as the editor, paired with o3-mini as the architect
aider --architect --model o3-mini --editor-model sonnet task_runner.py

# Use GPT-4o as the editor
aider --architect --model o3-mini --editor-model gpt-4o task_runner.py

# Use a local model as the editor (via Ollama)
aider --architect --model o3-mini --editor-model ollama/llama3.1 task_runner.py

You can also switch the editor mid-session:

architect> /editor-model sonnet

Step 6: Configure editor edit formats

Different editor models work best with different edit formats:

# editor-diff: the editor produces unified diffs (default, works well with most editors)
aider --architect --editor-edit-format editor-diff

# editor-whole: the editor rewrites entire files (use when diff-format produces errors)
aider --architect --editor-edit-format editor-whole

The editor-diff format is recommended for most use cases. Switch to editor-whole if the editor consistently produces malformed diffs.

Step 7: Auto-accept architect changes

By default, Aider shows you the architect's proposal and asks for confirmation before applying edits. In automated workflows, you can skip this:

# Auto-accept architect proposals without confirmation
aider --architect --auto-accept-architect

Or set it in .aider.conf.yml:

architect: true
auto-accept-architect: true

This is useful in CI/CD pipelines where you trust the model and want fully unattended operation.

Step 8: Combine modes in a single session

You are not locked into one mode. Switch fluidly:

# Start in code mode for simple edits
> Add a docstring to run_task

# Switch to architect for a complex change
> /chat-mode architect
architect> Refactor the task runner to use a plugin architecture

# Switch to ask mode to understand something
> /chat-mode ask
ask> How does the current error handling work?

# Back to code mode to apply a fix
> /chat-mode code
> Fix the error handling to log exceptions instead of silently swallowing them

Each mode switch preserves the full chat history. The LLM has context from every previous message regardless of mode.

What goes wrong

Mistake	How you notice it	The fix
Editor model produces malformed diffs	Aider reports "failed to apply edit" or produces garbled output	Try a different editor edit format: --editor-edit-format editor-whole. Or switch to a stronger editor model with /editor-model sonnet
Architect proposes a design that does not fit the codebase	The editor produces edits that conflict with existing code or introduce bugs	The architect only sees the repomap and chat files, not the full codebase. Add relevant files to the chat. Use /ask to discuss the design before entering architect mode
Using architect mode for trivial tasks	Aider takes longer to respond, costs more, and the architect's proposal is obvious	Use /code mode for simple changes. Architect mode is for tasks where the design is non-obvious. One-line fixes do not need a two-model pipeline
Weak editor model undermines a strong architect	The architect proposes a great design but the editor implements it poorly	Pair a strong architect with an equally capable editor. --editor-model sonnet or --editor-model gpt-4o are the safest defaults
Architect mode doubles your API costs	Your bill is higher than expected with no proportional quality improvement	Architect mode sends two API requests per prompt. For rapid iteration on small changes, use code mode. Reserve architect mode for complex tasks
Forgetting you are in architect mode	You type /code <simple fix> and it goes through two models unnecessarily	Check the prompt prefix. architect> means you are in architect mode. Switch back with /chat-mode code

Confirm it worked

Run this sequence. If every step succeeds, you have mastered architect mode:

# 1. Launch in architect mode with a reasoning model + code editor
cd ~/aider-architect
aider --architect --model o3-mini task_runner.py

# 2. Give a complex task that benefits from architectural thinking
#    The architect should propose a design before the editor writes code
architect> Add a task dependency system: tasks can depend on other tasks, and the runner 
should execute them in the correct order. Use topological sort.

# 3. Observe the two-pass output: first a design proposal, then file edits

# 4. Review the diff to confirm the implementation followed the design
> /diff

# 5. Switch to ask mode for a follow-up question
> /ask Does this handle circular dependencies?

# 6. Then switch to code mode for a quick fix
> /code Add a circular dependency detection step before sorting

If the architect proposes a coherent design, the editor implements it correctly, and you can fluidly switch between modes, architect mode is working.

Next: Multi-Model Workflows