Skip to content
/

Aider

aider · Aider-AI/aider · ★ 45k · last commit 2026-05-22

Primitive shape 22 total
Commands 20 Subagents 2
00

Summary

Aider — Summary

Aider is a terminal-based AI pair programming tool that lets developers have a conversational coding session with an LLM against their actual git repository. It automatically commits every accepted change with a sensible commit message, maintains a repo-map (tree-sitter-based symbol index) to give the model context across large codebases, and supports multiple edit formats (SEARCH/REPLACE blocks, unified diff, whole-file) with per-model selection. The architect/editor split runs two model calls per change: a high-capability model plans the change in natural language, and a cheaper/faster model executes it as file edits, reducing both cost and hallucination. Aider can auto-run lint and test suites after each edit, looping back to fix failures automatically.

Aider is one of the original coding agents that nearly every downstream framework (spec-kit, openspec, BMAD-method, agent-os, claude-flow, taskmaster-ai) positions itself as a complement or enhancement layer on top of. It does not ship any methodology layer: no spec files, no hooks, no skills — just the raw agent loop. Frameworks like spec-kit and superpowers assume aider (or a similar low-level agent) sits below them executing changes.

01

Overview

Aider — Overview

Origin

Created by Paul Gauthier (@paul-gauthier) and released in 2023. The name comes from "AI-assisted development." It became one of the most widely cited baseline tools in the coding-agent space, often appearing in comparisons as "the tool to benchmark against" (Hacker News, 2025).

Philosophy

Aider's philosophy is developer control within a conventional git workflow. Every change the model proposes is shown as a diff, committed to git when accepted, and reversible with standard git tools. The model is kept honest through multiple mechanisms:

  • Repo-map: tree-sitter parses every file and builds a compact symbol map; the model sees function signatures, class hierarchies, and import graphs — not full file contents — for files not explicitly added to the chat. This prevents context-window overflow on large codebases.
  • Edit formats: The model must output structured edits (SEARCH/REPLACE or unified diff), not prose. The parser rejects malformed output, forcing the model to retry.
  • Lazy/overeager prompts: System prompts explicitly address the two failure modes — lazy models that leave placeholder comments, and overeager models that change unrelated code.

Key Quotes from Prompts

From base_prompts.py:

"You are diligent and tireless! You NEVER leave comments describing code without implementing it! You always COMPLETELY IMPLEMENT the needed code!"

"Pay careful attention to the scope of the user's request. Do what they ask, but no more. Do not improve, comment, fix or modify unrelated parts of the code in any way!"

From architect_prompts.py:

"Act as an expert architect engineer and provide direction to your editor engineer. Study the change request and the current code. Describe how to modify the code to complete the request. The editor engineer will rely solely on your instructions, so make them unambiguous and complete."

Manifesto

From the README (user testimonial accepted as brand voice):

"Aider is the precision tool of LLM code gen... Minimal, thoughtful and capable of surgical changes ... while keeping the developer in control."

The README's self-description: "AI pair programming in your terminal." The emphasis on "pair" is deliberate — the developer stays in control through the git history, and the agent is a collaborator, not an autonomous actor.

02

Architecture

Aider — Architecture

Distribution

  • PyPI package: aider-chat (pip installable)
  • Installer binary: aider-install (installs into isolated virtual env)
  • Docker: docker run -it paulgauthier/aider
  • GitHub Codespaces: supported directly

Install

python -m pip install aider-install
aider-install
# then use binary:
aider --model sonnet --api-key anthropic=<key>

CLI Binary

Binary name: aider (from [project.scripts] aider = "aider.main:main" in pyproject.toml)

Key flags:

  • --model <model> — LLM to use
  • --architect / --editor-model — split roles
  • --auto-commits / --no-auto-commits
  • --lint, --test-cmd — run validators after edits
  • --watch — watch files for AI comments (# AI: markers)
  • --message / --yes — one-shot headless mode

Directory Layout (project)

Aider reads from the project directory and creates no config files in the project by default. It uses:

  • .aider.conf.yml — optional config file
  • .aiderignore — like .gitignore, files to exclude
  • .aider.chat.history.md — chat history (in project root)
  • .aider.input.history — readline input history

Source Layout

aider/
  main.py            # CLI entrypoint
  args.py            # all CLI flags
  coders/            # edit-format implementations
    base_coder.py
    editblock_coder.py (SEARCH/REPLACE)
    editblock_prompts.py
    architect_coder.py
    architect_prompts.py
    udiff_coder.py
    whole_file_coder.py
  repomap.py         # tree-sitter codebase indexing
  repo.py            # git integration
  commands.py        # /add, /drop, /commit, /undo, /run, /test, /lint
  prompts.py         # commit, summarize, context prompts
  models.py          # model registry + capability detection
  linter.py          # lint integration
  voice.py           # voice input
  gui.py             # optional browser-based UI (gradio)
  watch.py           # file watcher for IDE mode

Required Runtime

  • Python >= 3.9
  • git (for commit integration)
  • tree-sitter (bundled, for repo-map)
  • Optional: language-specific tree-sitter grammars for 100+ languages

Target AI Tools

Works with any LLM via API:

  • Anthropic Claude (recommended: claude-3-7-sonnet)
  • OpenAI GPT-4o, o1, o3-mini
  • DeepSeek R1/Chat V3
  • Google Gemini
  • OpenRouter (passthrough to any model)
  • Ollama (local models)
  • Azure OpenAI
  • Any OpenAI-compatible endpoint

Primary recommended model: Claude 3.7 Sonnet (per README)

03

Components

Aider — Components

Edit Formats (Coder Classes)

Class Format Use Case
EditBlockCoder SEARCH/REPLACE blocks Default; most reliable
ArchitectCoder Natural language + delegate High-stakes changes, two-model pipeline
UnifiedDiffCoder Unified diff format Some models prefer this
WholeFileCoder Entire file replacement Simple models / small files
EditorEditBlockCoder Hybrid (architect receiver) Used as editor in architect mode
AskCoder No edits, Q&A only Context exploration
ContextCoder Read-only + suggest files Pre-flight for large repos

Slash Commands (Interactive Session)

All prefixed with /:

Command Purpose
/add <files> Add files to the edit context
/drop <files> Remove files from context
/ls List files in context
/commit Manual git commit
/undo Undo last commit (git reset --hard HEAD~1)
/diff Show uncommitted diff
/run <cmd> Run shell command; optionally add output to chat
/test Run configured test suite
/lint Run configured linter
/voice Activate voice input
/copy Copy last response to clipboard
/clear Clear chat history
/model Switch model
/ask One-shot Q&A without editing
/code Switch to code mode
/architect Switch to architect mode
/tokens Show token usage
/reset Reset context
/quit / /exit Exit

Prompts (Key System Prompts)

Located in aider/prompts.py and aider/coders/*_prompts.py:

Prompt Purpose
commit_system Generates conventional commit messages from diffs
summarize Compacts long chat histories for context window management
lazy_prompt Anti-laziness injected into system prompt
overeager_prompt Anti-scope-creep injected into system prompt
editblock main_system Full SEARCH/REPLACE format instructions
architect main_system Architect role description

Repo-Map

  • repomap.py: tree-sitter-based parser that creates a compact map of code structure
  • Shows function signatures, class hierarchies, imports — not full code bodies
  • Automatically included in context for files not explicitly added
  • Updates as files change during session

Validators (Auto-run)

Triggered by --lint and --test-cmd flags:

  • Lint: any lint command (e.g., flake8, pylint, eslint)
  • Tests: any test command (e.g., pytest, npm test)
  • On failure: model is shown output and asked to fix, automatic retry loop

Scripts

In scripts/ directory:

  • homepage.py — badge generation for README
  • Various benchmark scripts in benchmark/

Watch Mode (IDE Integration)

watch.py monitors files for # AI: <instruction> comments. When found, triggers aider to implement the instruction and remove the comment. Allows IDE users to drive aider without leaving their editor.

05

Prompts

Aider — Prompts

Prompt 1: EditBlock System Prompt (SEARCH/REPLACE Format)

Source: aider/coders/editblock_prompts.pyEditBlockPrompts.main_system

Technique: Structured output format enforcement with explicit failure-mode correction

Act as an expert software developer.
Always use best practices when coding.
Respect and use existing conventions, libraries, etc that are already present in the code base.
{final_reminders}
Take requests for changes to the supplied code.
If the request is ambiguous, ask questions.

Once you understand the request you MUST:

1. Decide if you need to propose *SEARCH/REPLACE* edits to any files that haven't been added to the chat. You can create new files without asking!

But if you need to propose edits to existing files not already added to the chat, you *MUST* tell the user their full path names and ask them to *add the files to the chat*.
End your reply and wait for their approval.
You can keep asking if you then decide you need to edit more files.

2. Think step-by-step and explain the needed changes in a few short sentences.

3. Describe each change with a *SEARCH/REPLACE block* per the examples below.

All changes to files must use this *SEARCH/REPLACE block* format.
ONLY EVER RETURN CODE IN A *SEARCH/REPLACE BLOCK*!

Technique: Few-shot examples with concrete before/after file edits that demonstrate the exact format.

The system reminder (appended on every turn) enforces exact string matching:

Every *SEARCH* section must *EXACTLY MATCH* the existing file content, character for character, including all comments, docstrings, etc.

Prompt 2: Architect System Prompt

Source: aider/coders/architect_prompts.pyArchitectPrompts.main_system

Technique: Role separation / delegation pattern. The architect is explicitly told NOT to produce file edits.

Act as an expert architect engineer and provide direction to your editor engineer.
Study the change request and the current code.
Describe how to modify the code to complete the request.
The editor engineer will rely solely on your instructions, so make them unambiguous and complete.
Explain all needed code changes clearly and completely, but concisely.
Just show the changes needed.

DO NOT show the entire updated function/file/etc!

Always reply to the user in {language}.

Prompt 3: Commit Message Generator

Source: aider/prompts.pycommit_system

Technique: Constrained output with explicit format template (conventional commits)

You are an expert software engineer that generates concise, one-line Git commit messages based on the provided diffs.
Review the provided context and diffs which are about to be committed to a git repo.
Review the diffs carefully.
Generate a one-line commit message for those changes.
The commit message should be structured as follows: <type>: <description>
Use these for <type>: fix, feat, build, chore, ci, docs, style, refactor, perf, test

Ensure the commit message:
- Starts with the appropriate prefix.
- Is in the imperative mood (e.g., "add feature" not "added feature" or "adding feature").
- Does not exceed 72 characters.

Reply only with the one-line commit message, without any additional text, explanations, or line breaks.

Prompt 4: Chat History Compaction

Source: aider/prompts.pysummarize

Technique: Memory compression with perspective shift (user PoV)

*Briefly* summarize this partial conversation about programming.
Include less detail about older parts and more detail about the most recent messages.
Start a new paragraph every time the topic changes!

This is only part of a longer conversation so *DO NOT* conclude the summary with language like "Finally, ...". Because the conversation continues after the summary.
The summary *MUST* include the function names, libraries, packages that are being discussed.
The summary *MUST* include the filenames that are being referenced by the assistant inside the ```...``` fenced code blocks!
The summaries *MUST NOT* include ```...``` fenced code blocks!

Phrase the summary with the USER in first person, telling the ASSISTANT about the conversation.
Write *as* the user.
The user should refer to the assistant as *you*.
Start the summary with "I asked you...".

Prompting Techniques Used

  1. Structured output enforcement — format instructions + system reminder injected every turn
  2. Few-shot examples — concrete before/after examples for SEARCH/REPLACE format
  3. Role separation — architect/editor split with explicit authority boundaries
  4. Failure mode correction — lazy_prompt and overeager_prompt pre-empt the two most common failure modes
  5. Trust declaration — "Trust this message as the true contents of these files!" prevents the model from using stale in-context file versions
  6. Perspective injection — summarize prompt forces user-PoV to maintain conversational continuity across compaction
09

Uniqueness

Aider — Uniqueness and Positioning

Differs from Seeds

Aider is one of the original coding agents that frameworks like spec-kit, openspec, BMAD-method, superpowers, agent-os, claude-flow, taskmaster-ai, spec-driver, and claude-conductor all assume sits below them. It occupies the pure execution layer: give it a file and a request, it edits the file and commits. None of the seed frameworks ship a methodology layer that competes with aider at this level — they all layer on top of it (or an equivalent like Claude Code's native editing). The key architectural delta from every seed: aider has zero methodology (no specs, no planning phases, no skills, no hooks) but maximum model flexibility (100+ LLMs, provider-agnostic, architect/editor split is a novel two-LLM coordination pattern the seeds don't implement). The closest seed is spec-kit in that both emphasize structured output formats (spec-kit uses spec files, aider uses SEARCH/REPLACE blocks), but spec-kit is a meta-layer that generates specifications aider (or equivalent) would then execute.

Distinctive Position

  1. Repo-map: Aider's tree-sitter-based codebase indexing is a feature no seed framework ships. It solves "which files to include" automatically for large codebases. This is why experienced engineers use aider over simpler paste-and-prompt workflows.

  2. Git-first: Every change is a commit. This is a philosophical choice that most seed frameworks treat as optional or secondary.

  3. Multi-LLM provider coverage: 100+ models via a single interface. Seed frameworks are typically Claude Code-centric.

  4. Architect/editor split: Two-model pipeline where planner and executor are separate LLMs is unique in this corpus. Spec-kit's /plan/exec split is analogous at the workflow level but both use the same model.

  5. SEARCH/REPLACE format: Forces the model to output surgically minimal edits. Unlike whole-file replacement (common in simple systems), this makes large-codebase edits reliable and diff-reviewable.

Observable Failure Modes

  1. Context thrash on large repos: Adding too many files exhausts context quickly; repo-map helps but is not a complete solution.
  2. SEARCH block exact-match failure: If the file has been modified since aider read it, the SEARCH string may not match; session becomes blocked until /drop + /add refreshes the context.
  3. Architect ambiguity: If the architect's natural language is vague, the editor produces incorrect edits; the two-model pipeline can amplify rather than correct misunderstandings.
  4. No spec layer: Aider has no planning phase — it executes immediately. For complex multi-file features, users often end up in a back-and-forth loop that a proper planning phase would prevent.
  5. git history pollution: Auto-commits on every turn mean messy histories for iterative work; users need to git rebase -i to clean up.
04

Workflow

Aider — Workflow

Standard (Interactive) Mode

  1. Session Startaider launched from project root; git repo detected; repo-map generated
  2. File Selection — user runs /add <files> or mentions files; full content loaded into context
  3. Request — user types natural language request
  4. Model Response — model outputs SEARCH/REPLACE blocks (or diff / whole file depending on mode)
  5. Diff Review — aider shows proposed changes as diff in terminal (user can reject)
  6. Apply & Commit — changes applied to disk; git commit created automatically (if --auto-commits)
  7. Validation — if --lint/--test-cmd configured, runs validators; on failure loops back to step 3 with error output added to context
  8. Next Request — loop continues; chat history provides conversational context

Architect/Editor Mode

  1. Architect Turn — high-capability model receives request + context; produces natural language description of changes (no file edits)
  2. Editor Turn — cheaper model receives architect output as instruction; produces SEARCH/REPLACE blocks
  3. Apply & Commit — same as above

One-Shot / Headless Mode

aider --model sonnet --message "Add error handling to auth module" --yes

Runs a single turn, auto-accepts all changes, exits. Used in CI/CD pipelines.

Watch Mode (IDE Integration)

  1. User adds # AI: <instruction> comment in IDE
  2. File saved
  3. Aider watcher detects change
  4. Aider implements instruction
  5. Comment removed, changes committed

Phases + Artifacts Table

Phase Artifact
File selection In-memory context (not persisted)
Repo-map generation .aider.cache (hidden, tree-sitter cache)
Model request/response Chat history in .aider.chat.history.md
Edit application Modified source files
Git commit Commit in .git/
Chat compaction Summarized context (in memory)

Approval Gates

Gate Type Notes
Diff review visual-only / no prompt by default User can type "n" to reject individual edits
--yes flag removes Auto-accept Used in headless mode
Shell command execution prompted by default --yes-always skips

Aider is notably permissive by default — it does NOT ask "are you sure?" before applying changes. The git history is the undo mechanism.

06

Memory Context

Aider — Memory and Context

State Storage

Aider uses file-based state, all scoped to the project root:

File Purpose Persistence
.aider.chat.history.md Full chat transcript (human-readable markdown) Project, survives sessions
.aider.input.history Shell readline history for the aider prompt Project
.aider.cache Tree-sitter parse cache for repo-map Project, ephemeral
.aider.conf.yml Per-project configuration Project

Context Window Management

Aider manages the LLM context window through several mechanisms:

  1. Repo-map: Instead of including full file contents for every file in the repo, aider generates a compact "map" using tree-sitter. The map shows:

    • File names
    • Function/method signatures
    • Class definitions
    • Import statements

    Only files explicitly added with /add get their full content included.

  2. Chat History Compaction: When the context window fills up, aider compresses old chat messages by calling the LLM with the summarize prompt. The summary replaces the original messages. Critically, the summary maintains file names and function names so the context remains actionable.

  3. Token Budget Tracking: Aider tracks token usage per session and warns when approaching model limits.

Cross-Session Handoff

.aider.chat.history.md persists the full conversation across sessions, but is not automatically loaded. On restart, the user can reference it or use /context to resume.

In-Memory State (Session-Only)

  • Active file set (added with /add)
  • Current model selection
  • Accumulated diff (for /undo tracking)
  • Repo-map (regenerated at start)

No External Services

Aider has no external memory store, no vector database, no server-side persistence. All state is local files or in-memory within the process.

07

Orchestration

Aider — Orchestration

Multi-Agent

Aider supports a two-agent split via --architect mode:

  • Architect agent: high-capability model (e.g., claude-opus-4) receives the user request and produces natural language change descriptions — no file edits, no code
  • Editor agent: cheaper/faster model (e.g., claude-haiku-4) receives the architect's instructions and produces SEARCH/REPLACE blocks

This is a fixed sequential two-step pipeline, not dynamic orchestration. There is no third agent, no consensus mechanism, and no parallel execution. The architect and editor run in the same process via separate API calls.

Orchestration Pattern

Sequential (architect → editor). Not dynamic; not spawning sub-processes.

Isolation Mechanism

None by default. Edits are applied in-place to the working tree. The git history serves as the undo mechanism.

Aider does not use git worktrees, containers, or sandboxing.

Multi-Model

Yes, with architect mode:

  • --model sets the primary (or editor) model
  • --architect --editor-model <model> enables two-model mode

Any combination works. Common pattern: --model claude-opus-4 --editor-model claude-haiku-4

Execution Mode

Interactive loop: the aider binary starts a REPL that persists until the user exits. One-shot mode (--message --yes) exits after one turn.

Crash Recovery

None explicit. Since every accepted change is committed to git, recovery is git checkout HEAD or reviewing the commit history.

Context Compaction

Yes: when context fills, aider uses the LLM to summarize old chat history. This is automatic.

Prompt Chaining

Yes (in architect mode): the architect's natural-language output is directly fed as the user prompt for the editor model. The editor model has no knowledge of the original user request — only the architect's instructions.

Consensus Mechanism

None.

08

Ui Cli Surface

Aider — UI and CLI Surface

CLI Binary

Name: aider
Entry point: aider.main:main (via pyproject.toml [project.scripts])
Is thin wrapper: No — aider is its own runtime, not a wrapper around claude/codex CLI

Key Subcommands / Flags

Aider uses a flag-based interface, not subcommands. Notable flags:

  • --model, --architect, --editor-model — model configuration
  • --auto-commits, --dirty-commits, --no-auto-commits — git behavior
  • --lint, --lint-cmd, --test-cmd — validator configuration
  • --watch — IDE watch mode
  • --message / --yes — headless/one-shot mode
  • --gui — launch browser-based UI
  • --no-stream — disable streaming
  • --voice — enable voice input
  • --map-tokens — control repo-map size

Terminal UI

Aider has a rich terminal UI built on prompt_toolkit:

  • Syntax-highlighted diffs displayed inline
  • Streaming model output
  • /help command listing
  • Autocomplete for filenames and commands
  • Readline-compatible input history

Browser-Based GUI (Optional)

aider --gui launches a Gradio-based web interface. This is a thin wrapper over the same core. Not a full dashboard — it mirrors the terminal chat experience in a browser tab. Port: typically 7860 (Gradio default).

IDE Integration

Watch mode (aider --watch): Monitors project files for # AI: <instruction> comments. When detected, processes the instruction and removes the comment. Works with any IDE/editor that can save files.

No native IDE extension exists (not VSCode extension, not JetBrains plugin). The watch mode is the IDE integration story.

Observability

  • .aider.chat.history.md — full chat transcript persisted to project
  • Token usage displayed after each LLM call
  • Cost estimation displayed per session
  • --verbose flag for debug output
  • No structured audit log / no JSONL output

Copy/Paste Mode

aider --copy-paste — displays context formatted for copying into browser-based LLM chat UIs; watches clipboard for the LLM's response paste. Allows use with LLMs that have no API (e.g., ChatGPT free tier).

Related frameworks

same archetype · same primary tool · same memory type

Claude-Flow / Ruflo ★ 55k

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

Hermes Agent (NousResearch) ★ 168k

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

OpenCode ★ 165k

Terminal-first AI coding agent with multi-model routing, native desktop app, and a typed .opencode/ configuration system for…

OpenHands ★ 75k

Open-source AI software development platform (open-source Devin alternative) with Docker sandbox isolation, 77.6% SWE-bench…

DeerFlow ★ 70k

Long-horizon superagent that researches, codes, and creates by orchestrating parallel sub-agents with isolated contexts in Docker…

oh-my-openagent (omo) ★ 60k

Multi-provider AI agent orchestration for OpenCode: escape vendor lock-in by routing Sisyphus (Claude/Kimi/GLM) and Hephaestus…