Aider Architecture Map — Architecture Guide

01

System Overview

Aider is a terminal-based AI pair programmer that connects LLMs to real codebases. The user chats naturally, and Aider assembles context from the repo map, sends structured prompts to the model, parses edit instructions from the response, applies changes to files, lints the result, and auto-commits to git. The entire loop runs in a single Python process with no build step or daemon.

High-Level Architecture

graph TB
    subgraph User["User Layer"]
        TERM["Terminal
prompt-toolkit"]
        VOICE["Voice Input
Whisper API"]
        WATCH["File Watcher
watchfiles"]
        WEB["Web Scraper
playwright / httpx"]
    end

    subgraph Core["Core Loop"]
        IO["InputOutput
io.py"]
        CODER["Coder
base_coder.py"]
        CMDS["Commands
commands.py"]
    end

    subgraph Context["Context Engine"]
        REPOMAP["Repo Map
repomap.py"]
        HISTORY["Chat Summary
history.py"]
        CHUNKS["Chat Chunks
chat_chunks.py"]
    end

    subgraph LLM["LLM Layer"]
        MODELS["Model Registry
models.py"]
        SEND["Send Chat
litellm"]
    end

    subgraph Apply["Apply Layer"]
        EDIT["Edit Formats
coders/*.py"]
        LINT["Linter
linter.py"]
        GIT["Git Repo
repo.py"]
    end

    TERM --> IO
    VOICE --> IO
    WATCH --> IO
    WEB --> IO
    IO --> CODER
    CMDS --> CODER
    CODER --> REPOMAP
    CODER --> HISTORY
    CODER --> CHUNKS
    CHUNKS --> SEND
    MODELS --> SEND
    SEND --> EDIT
    EDIT --> LINT
    LINT --> GIT
    GIT -->|auto-commit| CODER

    style TERM fill:#14141e,stroke:#14b014,color:#e8e8f0
    style VOICE fill:#14141e,stroke:#14b014,color:#e8e8f0
    style WATCH fill:#14141e,stroke:#14b014,color:#e8e8f0
    style WEB fill:#14141e,stroke:#14b014,color:#e8e8f0
    style IO fill:#14141e,stroke:#00d4aa,color:#e8e8f0
    style CODER fill:#14141e,stroke:#00d4aa,color:#e8e8f0
    style CMDS fill:#14141e,stroke:#00d4aa,color:#e8e8f0
    style REPOMAP fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style HISTORY fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style CHUNKS fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style MODELS fill:#14141e,stroke:#9966ff,color:#e8e8f0
    style SEND fill:#14141e,stroke:#9966ff,color:#e8e8f0
    style EDIT fill:#14141e,stroke:#e87830,color:#e8e8f0
    style LINT fill:#14141e,stroke:#e87830,color:#e8e8f0
    style GIT fill:#14141e,stroke:#e87830,color:#e8e8f0

Context Engine

Tree-sitter parses every file to extract definitions and references. A PageRank graph ranks which symbols matter most for the current task, staying within the token budget.

tree-sitterNetworkX

Multi-Format Edits

Different models work best with different edit formats. Aider supports search/replace blocks, whole-file rewrites, unified diffs, patch format, and architect-delegated editing.

Python

Model Abstraction

A unified interface via litellm supports OpenAI, Anthropic, DeepSeek, Gemini, local models, and dozens more. Each model gets tuned settings for edit format, temperature, and token limits.

litellm

Git-Native Workflow

Every edit is auto-committed with a descriptive message. Users can /undo to revert, /diff to inspect, and always have a clean audit trail of AI-generated changes.

GitPython

02

Repo Map & Context Engine

The repo map is Aider's signature innovation. Instead of dumping entire files into the prompt, it builds a graph of every symbol definition and reference across the codebase, then uses PageRank to select the most relevant code context for the current task -- all within a configurable token budget.

Repo Map Pipeline

graph LR
    subgraph Parse["1. Parse"]
        TS["tree-sitter
Parser"]
        PYG["Pygments
Fallback"]
    end

    subgraph Extract["2. Extract"]
        DEFS["Definitions
name.definition.*"]
        REFS["References
name.reference.*"]
        TAGS["Tag Cache
SQLite / diskcache"]
    end

    subgraph Rank["3. Rank"]
        GRAPH["MultiDiGraph
files as nodes"]
        PR["PageRank
personalized"]
    end

    subgraph Render["4. Render"]
        TC["TreeContext
AST-aware snippets"]
        OUT["Markdown
Repo Map"]
    end

    TS --> DEFS
    TS --> REFS
    PYG --> REFS
    DEFS --> TAGS
    REFS --> TAGS
    TAGS --> GRAPH
    GRAPH --> PR
    PR --> TC
    TC --> OUT

    style TS fill:#14141e,stroke:#66ff66,color:#e8e8f0
    style PYG fill:#14141e,stroke:#66ff66,color:#e8e8f0
    style DEFS fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style REFS fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style TAGS fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style GRAPH fill:#14141e,stroke:#00d4aa,color:#e8e8f0
    style PR fill:#14141e,stroke:#00d4aa,color:#e8e8f0
    style TC fill:#14141e,stroke:#9966ff,color:#e8e8f0
    style OUT fill:#14141e,stroke:#9966ff,color:#e8e8f0

PageRank Personalization

Files currently in the chat get a 50x weight boost. Identifiers mentioned in the conversation get 10x. Named symbols 8+ characters long get 10x. Reference counts are square-rooted to prevent any single high-frequency symbol from dominating the graph. This ensures the map stays focused on what matters for the current task.

Tag Extraction

Tree-sitter queries extract name.definition.* tags (class/function definitions) and name.reference.* tags (symbol usage). Each tag is a named tuple of (rel_fname, fname, line, name, kind). Results are cached in a SQLite-backed disk cache keyed by file modification time. For languages with incomplete tree-sitter grammars (like C++), Aider falls back to Pygments lexer tokenization.

Parameter	Default	Description
`map_tokens`	1024	Base token budget for the repo map output
`map_mul_no_files`	8x	Multiplier when no files are in chat (expands map scope)
`refresh`	auto	Cache strategy: auto, manual, files, always
Graph algorithm	PageRank	NetworkX personalized PageRank on MultiDiGraph
Edge weight	sqrt(count)	Square root of reference frequency prevents domination
Line truncation	100 chars	Lines in rendered map are capped at 100 characters

03

Coder & Edit Formats

The Coder is the heart of Aider -- it orchestrates the entire chat-edit-commit loop. A base class handles context assembly, LLM communication, and git integration. Subclasses implement different edit formats, each with its own prompts and parsing logic. The model's capabilities determine which format is used.

Coder Class Hierarchy

graph TD
    BASE["Coder
(base_coder.py)"]

    BASE --> EB["EditBlockCoder
search/replace blocks"]
    BASE --> WF["WholeFileCoder
full file rewrites"]
    BASE --> UD["UDiffCoder
unified diff format"]
    BASE --> PA["PatchCoder
patch format"]
    BASE --> ASK["AskCoder
read-only Q&A"]
    BASE --> ARCH["ArchitectCoder
plan + delegate"]
    BASE --> CTX["ContextCoder
context exploration"]
    BASE --> HELP["HelpCoder
documentation"]

    EB --> EBF["EditBlockFencedCoder"]
    EB --> EBFN["EditBlockFuncCoder"]
    WF --> WFF["WholeFileFuncCoder"]
    WF --> SWF["SingleWholeFileFuncCoder"]

    ARCH --> EED["EditorEditBlockCoder"]
    ARCH --> EWH["EditorWholeCoder"]
    ARCH --> EDF["EditorDiffFencedCoder"]

    style BASE fill:#14141e,stroke:#00d4aa,color:#e8e8f0
    style EB fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style WF fill:#14141e,stroke:#e87830,color:#e8e8f0
    style UD fill:#14141e,stroke:#9966ff,color:#e8e8f0
    style PA fill:#14141e,stroke:#4488ee,color:#e8e8f0
    style ASK fill:#14141e,stroke:#14b014,color:#e8e8f0
    style ARCH fill:#14141e,stroke:#cc44cc,color:#e8e8f0
    style CTX fill:#14141e,stroke:#14b014,color:#e8e8f0
    style HELP fill:#14141e,stroke:#14b014,color:#e8e8f0
    style EBF fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style EBFN fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style WFF fill:#14141e,stroke:#e87830,color:#e8e8f0
    style SWF fill:#14141e,stroke:#e87830,color:#e8e8f0
    style EED fill:#14141e,stroke:#cc44cc,color:#e8e8f0
    style EWH fill:#14141e,stroke:#cc44cc,color:#e8e8f0
    style EDF fill:#14141e,stroke:#cc44cc,color:#e8e8f0

Search/Replace Blocks

The default format. The LLM writes <<<<<<< SEARCH / ======= / >>>>>>> REPLACE blocks. Aider matches the search text in the file, then substitutes. Supports fuzzy matching and whitespace flexibility.

diff edit

Whole File Rewrite

The LLM outputs the entire file content. Simple and reliable for smaller files or less capable models. Higher token cost but zero parsing ambiguity.

whole

Unified Diff

Standard unified diff format with @@ hunks. Works well with models trained on code review data. Lower token cost than whole-file for targeted changes.

udiff

Architect Mode

Two-model workflow: an "architect" model plans changes in natural language, then an "editor" model executes the plan using one of the concrete edit formats. Ideal for complex refactoring.

architect

Core Execution Flow

Coder Run Loop

graph LR
    A["run()"] --> B["preproc_user_input()"]
    B --> C["format_chat_chunks()"]
    C --> D["send_message()"]
    D --> E["show_send_output_stream()"]
    E --> F["apply_updates()"]
    F --> G["apply_edits()"]
    G --> H["lint()"]
    H --> I["auto_commit()"]
    I -->|"loop"| A

    style A fill:#14141e,stroke:#00d4aa,color:#e8e8f0
    style B fill:#14141e,stroke:#00d4aa,color:#e8e8f0
    style C fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style D fill:#14141e,stroke:#9966ff,color:#e8e8f0
    style E fill:#14141e,stroke:#9966ff,color:#e8e8f0
    style F fill:#14141e,stroke:#e87830,color:#e8e8f0
    style G fill:#14141e,stroke:#e87830,color:#e8e8f0
    style H fill:#14141e,stroke:#e84040,color:#e8e8f0
    style I fill:#14141e,stroke:#14b014,color:#e8e8f0

Fuzzy Matching in Search/Replace

When the LLM's search text doesn't exactly match the file, Aider tries a multi-stage fallback: exact match, whitespace-flexible match, ellipsis expansion, and finally edit-distance fuzzy matching. This compensates for models that slightly misquote existing code.

04

Model Abstraction Layer

Aider uses litellm as a universal LLM adapter, supporting 100+ model providers through a single interface. On top of litellm, Aider maintains its own ModelSettings registry that maps each model to its optimal edit format, token limits, capabilities, and quirks.

Model Configuration Flow

graph TD
    subgraph Registry["Model Registry"]
        STATIC["Static Lists
OPENAI_MODELS
ANTHROPIC_MODELS"]
        YAML["model-settings.yml
Package Resource"]
        USER["User Config
register_models()"]
        ALIAS["MODEL_ALIASES
sonnet, opus, gpt-4o..."]
    end

    subgraph Model["Model Instance"]
        MS["ModelSettings
edit_format, streaming
use_repo_map, tokens"]
        MOD["Model
token counting
env validation"]
    end

    subgraph Roles["Model Roles"]
        MAIN["Main Model
Primary editor"]
        WEAK["Weak Model
Commit messages
summaries"]
        EDITOR["Editor Model
Architect delegate"]
    end

    subgraph Providers["Providers via litellm"]
        OAI["OpenAI"]
        ANT["Anthropic"]
        DS["DeepSeek"]
        GEM["Gemini"]
        OR["OpenRouter"]
        LOCAL["Local / Ollama"]
    end

    STATIC --> MS
    YAML --> MS
    USER --> MS
    ALIAS --> MOD
    MS --> MOD
    MOD --> MAIN
    MOD --> WEAK
    MOD --> EDITOR
    MAIN --> OAI
    MAIN --> ANT
    MAIN --> DS
    MAIN --> GEM
    MAIN --> OR
    MAIN --> LOCAL

    style STATIC fill:#14141e,stroke:#9966ff,color:#e8e8f0
    style YAML fill:#14141e,stroke:#9966ff,color:#e8e8f0
    style USER fill:#14141e,stroke:#9966ff,color:#e8e8f0
    style ALIAS fill:#14141e,stroke:#9966ff,color:#e8e8f0
    style MS fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style MOD fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style MAIN fill:#14141e,stroke:#00d4aa,color:#e8e8f0
    style WEAK fill:#14141e,stroke:#14b014,color:#e8e8f0
    style EDITOR fill:#14141e,stroke:#cc44cc,color:#e8e8f0
    style OAI fill:#14141e,stroke:#4488ee,color:#e8e8f0
    style ANT fill:#14141e,stroke:#e87830,color:#e8e8f0
    style DS fill:#14141e,stroke:#4488ee,color:#e8e8f0
    style GEM fill:#14141e,stroke:#4488ee,color:#e8e8f0
    style OR fill:#14141e,stroke:#4488ee,color:#e8e8f0
    style LOCAL fill:#14141e,stroke:#4488ee,color:#e8e8f0

Model Role	Purpose	Examples
`main_model`	Primary code editor -- handles all editing tasks	Claude Sonnet, GPT-4o, DeepSeek Chat V3
`weak_model`	Fast fallback for commit messages, summaries, and simple tasks	GPT-4o-mini, Claude Haiku
`editor_model`	Executes the architect's plan in architect mode	Same as main or a dedicated model

Token Budget Allocation

The model's context window is divided strategically: 1/8 of the total context is allocated to the repo map by default via get_repo_map_tokens(). The remaining budget goes to chat history, file contents, and system prompts. When thinking/reasoning tokens are enabled, a separate budget is carved out (configurable via set_thinking_tokens()).

ModelSettings Fields

Field	Type	Purpose
`name`	str	Model identifier (e.g. "claude-sonnet-4-5")
`edit_format`	str	Optimal edit format: diff, whole, udiff, patch, architect
`use_repo_map`	bool	Whether this model benefits from repo map context
`streaming`	bool	Supports streaming responses
`weak_model_name`	str	Which model to use for lightweight tasks
`reasoning_tag`	str	Tag name for extended thinking output
`accepts_settings`	list	Which API parameters this model supports

05

Git Integration

Aider treats git as a first-class collaboration tool. Every AI edit is automatically committed with a descriptive message (generated by the weak model). Users can undo changes, inspect diffs, and maintain a clean audit trail. The GitRepo class wraps GitPython for all repository operations.

Git Workflow

graph LR
    subgraph Before["Pre-Edit"]
        DIRTY["Check Dirty Files"]
        DCOMMIT["Dirty Commit
(user's changes)"]
    end

    subgraph Edit["AI Edit"]
        APPLY["Apply Edits
to Files"]
        LINT["Lint & Fix"]
    end

    subgraph After["Post-Edit"]
        DIFF["Generate Diff"]
        MSG["Weak Model
Commit Message"]
        COMMIT["Auto-Commit
aider: description"]
    end

    subgraph Undo["Undo System"]
        HASH["Track Commit
Hashes"]
        REVERT["git revert
/undo command"]
    end

    DIRTY --> DCOMMIT
    DCOMMIT --> APPLY
    APPLY --> LINT
    LINT --> DIFF
    DIFF --> MSG
    MSG --> COMMIT
    COMMIT --> HASH
    HASH --> REVERT

    style DIRTY fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style DCOMMIT fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style APPLY fill:#14141e,stroke:#e87830,color:#e8e8f0
    style LINT fill:#14141e,stroke:#e84040,color:#e8e8f0
    style DIFF fill:#14141e,stroke:#14b014,color:#e8e8f0
    style MSG fill:#14141e,stroke:#9966ff,color:#e8e8f0
    style COMMIT fill:#14141e,stroke:#14b014,color:#e8e8f0
    style HASH fill:#14141e,stroke:#00d4aa,color:#e8e8f0
    style REVERT fill:#14141e,stroke:#00d4aa,color:#e8e8f0

Dirty Commit Handling

Before applying AI edits, Aider checks for uncommitted user changes. If found, it creates a separate "dirty commit" to preserve the user's work, keeping AI and human changes in distinct commits.

Attribution

Configurable via --attribute-author and --attribute-committer. Aider can modify GIT_AUTHOR_NAME and GIT_COMMITTER_NAME to clearly mark AI-generated commits in the history.

File Tracking

Uses GitPython's blob iteration to enumerate tracked files, supplemented with staged files from the index. Results are cached by commit hash to avoid repeated tree traversals.

Undo System

Aider tracks aider_commit_hashes for every AI commit. The /undo command reverts the last aider commit, giving users confidence to experiment freely.

06

Chat Modes & Commands

Aider supports multiple chat modes that change how the AI processes requests, plus a rich slash command system for file management, model switching, and workflow control. The Commands class uses method-naming convention where any cmd_* method becomes a slash command.

Chat Mode Architecture

graph TD
    subgraph Modes["Chat Modes"]
        CODE["/code
Edit files directly"]
        ASK["/ask
Read-only Q&A"]
        ARCHITECT["/architect
Plan + delegate"]
        CONTEXT["/context
Explore codebase"]
        HELP["/help
Documentation"]
    end

    subgraph Flow["Mode Resolution"]
        INPUT["User Input"]
        ROUTE["Mode Router"]
        CODER["Active Coder
Instance"]
    end

    INPUT --> ROUTE
    ROUTE --> CODE
    ROUTE --> ASK
    ROUTE --> ARCHITECT
    ROUTE --> CONTEXT
    ROUTE --> HELP
    CODE --> CODER
    ASK --> CODER
    ARCHITECT --> CODER

    style CODE fill:#14141e,stroke:#e87830,color:#e8e8f0
    style ASK fill:#14141e,stroke:#14b014,color:#e8e8f0
    style ARCHITECT fill:#14141e,stroke:#cc44cc,color:#e8e8f0
    style CONTEXT fill:#14141e,stroke:#00d4aa,color:#e8e8f0
    style HELP fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style INPUT fill:#14141e,stroke:#4488ee,color:#e8e8f0
    style ROUTE fill:#14141e,stroke:#4488ee,color:#e8e8f0
    style CODER fill:#14141e,stroke:#00d4aa,color:#e8e8f0

Category	Commands	Purpose
File Management	`/add` `/drop` `/read-only` `/ls`	Control which files are in the chat context
Mode Switching	`/code` `/ask` `/architect` `/context`	Change how the AI processes requests
Model Control	`/model` `/weak-model` `/editor-model`	Switch LLMs on the fly
Git Operations	`/commit` `/diff` `/undo` `/git`	Manage version control directly
Dev Workflow	`/lint` `/test` `/run`	Run linters, tests, and shell commands
Context	`/map` `/map-refresh` `/tokens`	Inspect and manage token usage
Input Methods	`/voice` `/paste` `/web` `/editor`	Alternative input sources: mic, clipboard, URLs
Session	`/clear` `/reset` `/save` `/load`	Manage chat history and session state

07

Linter & Auto-Fix

After every edit, Aider runs the linter to catch syntax errors and style issues. If problems are found, they're packaged with contextual code snippets and fed back to the LLM for automatic correction -- creating a self-healing edit loop.

Lint Pipeline

graph TD
    subgraph Input["Edited File"]
        FILE["modified.py"]
    end

    subgraph Detect["Language Detection"]
        LANG["filename_to_lang()"]
    end

    subgraph Checkers["Lint Checkers"]
        BASIC["basic_lint()
tree-sitter AST
ERROR nodes"]
        COMPILE["lint_python_compile()
Python compile()"]
        FLAKE["flake8_lint()
selective checks"]
        CUSTOM["Custom Linter
user-defined cmd"]
    end

    subgraph Output["Error Handling"]
        RESULT["LintResult
text + line numbers"]
        CTX["TreeContext
marked error lines"]
        FEEDBACK["Feed to LLM
Fix any errors below"]
    end

    FILE --> LANG
    LANG --> BASIC
    LANG --> COMPILE
    LANG --> FLAKE
    LANG --> CUSTOM
    BASIC --> RESULT
    COMPILE --> RESULT
    FLAKE --> RESULT
    CUSTOM --> RESULT
    RESULT --> CTX
    CTX --> FEEDBACK

    style FILE fill:#14141e,stroke:#e87830,color:#e8e8f0
    style LANG fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style BASIC fill:#14141e,stroke:#66ff66,color:#e8e8f0
    style COMPILE fill:#14141e,stroke:#4488ee,color:#e8e8f0
    style FLAKE fill:#14141e,stroke:#9966ff,color:#e8e8f0
    style CUSTOM fill:#14141e,stroke:#cc44cc,color:#e8e8f0
    style RESULT fill:#14141e,stroke:#e84040,color:#e8e8f0
    style CTX fill:#14141e,stroke:#e84040,color:#e8e8f0
    style FEEDBACK fill:#14141e,stroke:#00d4aa,color:#e8e8f0

Tree-Sitter Syntax Check

Parses code into an AST and traverses for ERROR nodes or missing required nodes. Language-agnostic syntax validation for any language with a tree-sitter grammar.

tree-sitter

Python Pipeline

Python files get a three-stage check: tree-sitter AST validation, compile() verification, and selective flake8 analysis. Each stage catches progressively subtler issues.

flake8

Custom Linters

Users can register custom lint commands per language via set_linter(lang, cmd) or set a global fallback. Commands are executed via shell with proper quoting.

shell

Error Context

Errors are formatted with TreeContext showing the surrounding code with problem lines highlighted using block characters. This gives the LLM precise context for auto-repair.

feedback

TypeScript Limitation

The tree-sitter linter explicitly skips TypeScript files due to grammar incompatibilities. For TypeScript projects, use a custom linter command (e.g., tsc --noEmit) instead.

08

I/O, Voice & Watch Mode

Aider provides a rich terminal interface with multiple input methods: keyboard with autocompletion, voice transcription via Whisper, file watching for IDE integration, and web scraping to pull documentation into context. Output is streamed as styled Markdown.

Input/Output Architecture

graph LR
    subgraph Input["Input Methods"]
        KB["Keyboard
prompt-toolkit
vi/emacs modes"]
        VC["Voice
sounddevice
Whisper API"]
        FW["File Watcher
watchfiles
AI comments"]
        WS["Web Scraper
playwright
httpx + pandoc"]
        ED["External Editor
Ctrl+X E"]
    end

    subgraph Process["InputOutput (io.py)"]
        AC["AutoCompleter
files, commands
tokenized content"]
        HIST["Input History
readline compatible"]
    end

    subgraph Output["Output"]
        MD["MarkdownStream
Rich console"]
        LOG["Chat Log
file-based"]
    end

    KB --> AC
    VC --> Process
    FW --> Process
    WS --> Process
    ED --> Process
    AC --> HIST
    Process --> MD
    Process --> LOG

    style KB fill:#14141e,stroke:#14b014,color:#e8e8f0
    style VC fill:#14141e,stroke:#e87830,color:#e8e8f0
    style FW fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style WS fill:#14141e,stroke:#4488ee,color:#e8e8f0
    style ED fill:#14141e,stroke:#9966ff,color:#e8e8f0
    style AC fill:#14141e,stroke:#00d4aa,color:#e8e8f0
    style HIST fill:#14141e,stroke:#00d4aa,color:#e8e8f0
    style MD fill:#14141e,stroke:#cc44cc,color:#e8e8f0
    style LOG fill:#14141e,stroke:#cc44cc,color:#e8e8f0

Watch Mode

Monitors files for AI comment markers (// ai! for code edits, # ai? for questions). Changed files are auto-added to chat, and the surrounding code context is extracted using TreeContext. Integrates seamlessly with any IDE.

Voice Input

Records audio via sounddevice, monitors levels with a visual progress bar, and transcribes through OpenAI's Whisper API. Handles device selection and auto-converts large recordings from WAV to MP3.

Web Scraping

Fetches URLs via Playwright (for JS-heavy sites) or httpx (for static content). HTML is slimmed (SVGs, images, data URIs removed) and converted to Markdown via pandoc for clean LLM context.

Terminal UI

Built on prompt-toolkit with vi/emacs editing modes, syntax highlighting via Pygments, Rich console for styled Markdown output, and context-aware autocompletion spanning files, commands, and code tokens.

09

Context Management

Aider carefully manages the LLM context window. Chat history is compressed when it grows too large, file contents are assembled into structured message chunks, and the repo map dynamically adjusts its scope based on available token budget.

Context Assembly

graph TD
    subgraph Budget["Token Budget"]
        CTX["Context Window
model max tokens"]
    end

    subgraph Components["Message Components"]
        SYS["System Prompt
edit format rules"]
        MAP["Repo Map
1/8 of context"]
        FILES["Chat Files
full contents"]
        RO["Read-Only Files
reference context"]
        HIST["Chat History
done_messages"]
        CUR["Current Message
user input"]
    end

    subgraph Compress["Overflow Handling"]
        SUMMARY["ChatSummary
LLM-generated
head compression"]
        TRUNC["Truncate Map
binary search
on token count"]
    end

    CTX --> SYS
    CTX --> MAP
    CTX --> FILES
    CTX --> RO
    CTX --> HIST
    CTX --> CUR
    HIST -->|"too_big()"| SUMMARY
    MAP -->|"budget exceeded"| TRUNC

    style CTX fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style SYS fill:#14141e,stroke:#9966ff,color:#e8e8f0
    style MAP fill:#14141e,stroke:#66ff66,color:#e8e8f0
    style FILES fill:#14141e,stroke:#e87830,color:#e8e8f0
    style RO fill:#14141e,stroke:#14b014,color:#e8e8f0
    style HIST fill:#14141e,stroke:#00d4aa,color:#e8e8f0
    style CUR fill:#14141e,stroke:#4488ee,color:#e8e8f0
    style SUMMARY fill:#14141e,stroke:#cc44cc,color:#e8e8f0
    style TRUNC fill:#14141e,stroke:#cc44cc,color:#e8e8f0

Recursive Summarization

When chat history exceeds the token limit, ChatSummary splits messages into "head" and "tail" at an assistant-message boundary. The head is sent to the LLM for summarization while the tail is preserved verbatim (keeping recent context intact). If the result still exceeds the budget, the process repeats recursively with increasing depth.

Context Component	Priority	Budget Strategy
System prompt	Fixed	Always included in full; defines edit format rules
Current user message	Fixed	Always included; the active request
Chat file contents	High	Full file contents of /add-ed files
Read-only files	High	Full contents but not editable by the LLM
Chat history	Medium	Compressed via recursive summarization when overflow
Repo map	Flexible	Binary search on content to hit token target (within 15%)

10

Module Map

Aider's codebase is organized as a flat Python package with ~45 modules in the root aider/ directory, plus a coders/ subpackage containing all edit format implementations. The queries/ directory holds tree-sitter query files for language-specific tag extraction.

Module Dependencies

graph TD
    subgraph Entry["Entry Points"]
        MAIN["main.py
CLI entry, arg parsing"]
        GUI["gui.py
browser UI"]
        ONBOARD["onboarding.py
first-run setup"]
    end

    subgraph Core["Core Modules"]
        CODER["coders/
base_coder.py
+ 15 edit formats"]
        CMDS["commands.py
slash commands"]
        IO["io.py
terminal I/O"]
        PROMPTS["prompts.py
system prompts"]
    end

    subgraph Context["Context Layer"]
        REPOMAP["repomap.py
PageRank context"]
        HISTORY["history.py
chat compression"]
        SCRAPE["scrape.py
web fetching"]
    end

    subgraph Model["Model Layer"]
        MODELS["models.py
settings + registry"]
        LLM["llm.py
litellm config"]
        SENDCHAT["sendchat.py
message validation"]
    end

    subgraph Tools["Tool Modules"]
        LINTER["linter.py
syntax checking"]
        REPO["repo.py
git operations"]
        VOICE["voice.py
audio recording"]
        WATCH["watch.py
file monitoring"]
        DIFFS["diffs.py
diff display"]
        EDITOR["editor.py
external editor"]
    end

    subgraph Support["Support"]
        ARGS["args.py
CLI arguments"]
        ANALYTICS["analytics.py
usage tracking"]
        UTILS["utils.py
shared helpers"]
        SPECIAL["special.py
special files"]
    end

    MAIN --> CODER
    MAIN --> MODELS
    MAIN --> IO
    MAIN --> ARGS
    CODER --> REPOMAP
    CODER --> CMDS
    CODER --> HISTORY
    CODER --> REPO
    CODER --> LINTER
    CODER --> LLM
    CMDS --> IO
    REPOMAP --> MODELS
    MODELS --> LLM
    IO --> VOICE
    IO --> WATCH

    style MAIN fill:#14141e,stroke:#00d4aa,color:#e8e8f0
    style GUI fill:#14141e,stroke:#00d4aa,color:#e8e8f0
    style ONBOARD fill:#14141e,stroke:#00d4aa,color:#e8e8f0
    style CODER fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style CMDS fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style IO fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style PROMPTS fill:#14141e,stroke:#e8c840,color:#e8e8f0
    style REPOMAP fill:#14141e,stroke:#66ff66,color:#e8e8f0
    style HISTORY fill:#14141e,stroke:#66ff66,color:#e8e8f0
    style SCRAPE fill:#14141e,stroke:#66ff66,color:#e8e8f0
    style MODELS fill:#14141e,stroke:#9966ff,color:#e8e8f0
    style LLM fill:#14141e,stroke:#9966ff,color:#e8e8f0
    style SENDCHAT fill:#14141e,stroke:#9966ff,color:#e8e8f0
    style LINTER fill:#14141e,stroke:#e87830,color:#e8e8f0
    style REPO fill:#14141e,stroke:#e87830,color:#e8e8f0
    style VOICE fill:#14141e,stroke:#e87830,color:#e8e8f0
    style WATCH fill:#14141e,stroke:#e87830,color:#e8e8f0
    style DIFFS fill:#14141e,stroke:#e87830,color:#e8e8f0
    style EDITOR fill:#14141e,stroke:#e87830,color:#e8e8f0
    style ARGS fill:#14141e,stroke:#4488ee,color:#e8e8f0
    style ANALYTICS fill:#14141e,stroke:#4488ee,color:#e8e8f0
    style UTILS fill:#14141e,stroke:#4488ee,color:#e8e8f0
    style SPECIAL fill:#14141e,stroke:#4488ee,color:#e8e8f0

Directory	Contents	Purpose
`aider/`	~45 Python modules	Core application: CLI, I/O, models, git, linter, voice, watch
`aider/coders/`	~38 files	Edit format implementations: base coder + 15 format variants with paired prompts
`aider/queries/`	Tree-sitter .scm files	Language-specific queries for definition/reference extraction
`aider/resources/`	YAML, text files	Model settings, help text, and static configuration
`aider/website/`	Jekyll site source	Documentation at aider.chat (deployed separately)
`tests/`	Test suite	Unit and integration tests
`benchmark/`	Benchmark harness	Exercism-based coding benchmarks for model evaluation