The lay of the land

Citations pinned at aider@5dc9490 (cloned 2026-07-08).

Aider is a single Python package. After setup, main() enters a plain while True: coder.run() and catches a SwitchCoder exception to swap the live coder between turns (aider/aider/main.py:1159-1177). The agent core is one class, Coder, subclassed by ~14 registered "coders" — one per edit format — chosen at runtime by matching a string against the coders.__all__ registry (aider/aider/coders/base_coder.py:190-194, aider/aider/coders/init.py:18-34).

The defining fact, the one everything else follows from: Aider has no model-driven tool loop. On the live path the model never emits a tool_use block. Instead the harness pre-loads context, the model replies once in a strict edit format (by default SEARCH/REPLACE blocks), and the harness parses that prose reply and applies the edits itself. Delegation, when it happens, is likewise in-process: an architect coder hands its plan to a freshly-built editor coder via Coder.create, not to a spawned agent (aider/aider/coders/architect_coder.py:11-48). Every organ Claude Code has is present here — it is just realized through parsing text, not dispatching tools.

The loop

Coder.run() is the outer REPL: read user input, call run_one() (aider/aider/coders/base_coder.py:876-892). run_one() is the real agentic turn loop, and it is startlingly small:

while message:
    self.reflected_message = None
    list(self.send_message(message))

    if not self.reflected_message:
        break

    if self.num_reflections >= self.max_reflections:
        self.io.tool_warning(f"Only {self.max_reflections} reflections allowed, stopping.")
        return

    self.num_reflections += 1
    message = self.reflected_message

The loop turns only if self.reflected_message got set during the turn, and is hard-capped at max_reflections = 3 (aider/aider/coders/base_coder.py:924-944, 100-101). A turn itself — send_message — appends the user message, assembles and token-checks the prompt, streams the completion, then post-processes the text reply (aider/aider/coders/base_coder.py:1419-1431). That post-processing is where the "agency" lives: apply_updates() parses and applies the edit blocks, and any failure downstream — a non-matching patch, a lint error, a failed test, a file the model asked to add — is funnelled back into reflected_message so the next iteration carries it (aider/aider/coders/base_coder.py:1585-1623). So Claude Code's "detect tool_use, execute, loop" becomes Aider's "parse edit blocks from prose, apply, and loop only on failure feedback" — a single reflection channel with a 3-iteration budget instead of an open-ended tool loop.

Tools and the gate

A "tool" in Aider is an edit format — a Coder subclass carrying the full tool anatomy, only spelled differently:

• Name. edit_format = "diff" (aider/aider/coders/editblock_coder.py:18); the dispatcher scans the registry for the subclass whose edit_format matches (aider/aider/coders/base_coder.py:190-194).
• Schema — in prose, not JSON. The system prompt mandates the exact syntax: "All changes to files must use this SEARCH/REPLACE block format. ONLY EVER RETURN CODE IN A SEARCH/REPLACE BLOCK!" (aider/aider/coders/editblock_prompts.py:8-30), reinforced with few-shot examples.
• Parser / validator. get_edits() runs find_original_update_blocks, which regex-scans the reply for $^<{5,9} SEARCH>?$, $^={5,9}$ and $^>{5,9} REPLACE$ markers (aider/aider/coders/editblock_coder.py:386-394, 439).
• Executor. apply_edits() anchors each SEARCH body against the file by exact line match (perfect_replace) — flexible only about uniform leading whitespace — and, if the target file doesn't match, retries the block against every other file in the chat (aider/aider/coders/editblock_coder.py:41-74, 146-154).

When a block fails to anchor, apply_edits raises a ValueError whose message is a repair-grade report: # N SEARCH/REPLACE blocks failed to match!, the offending block echoed back, a Did you mean to match some of these actual lines… hint drawn from find_similar_lines, and the rule "The SEARCH section must exactly match an existing block of lines including all white space, comments, indentation…" (aider/aider/coders/editblock_coder.py:84-124, 602-628). apply_updates() catches that ValueError and stores the whole report in self.reflected_message, so the model gets to retry against the budget (aider/aider/coders/base_coder.py:2296-2316).

Notably, JSON-schema function-call tools exist in the tree but are dead code. EditBlockFunctionCoder carries a full OpenAI functions schema — a replace_lines call with path / original_lines / updated_lines (aider/aider/coders/editblock_func_coder.py:10-58) — but its __init__ immediately raises RuntimeError("Deprecated, needs to be refactored to support get_edits/apply_edits") (aider/aider/coders/editblock_func_coder.py:61), it is never imported into the coders.__all__ registry, and a sibling SingleWholeFileFunctionCoder is explicitly commented out (aider/aider/coders/init.py:16). Tellingly, even that dead function coder imports and re-uses the same do_replace (aider/aider/coders/editblock_func_coder.py:5): the structured JSON would still have to anchor its original_lines to the file — the format changes the parse surface, not the anchor requirement.

The gate. The single approval primitive is InputOutput.confirm_ask() — a terminal Y/N prompt with (A)ll / (S)kip all / persistent (D)on't ask again (aider/aider/io.py:807-925). Between a parsed edit and the filesystem sits prepare_to_edit → allowed_to_edit: files already in the chat are pre-authorized (the human added them — that was the grant), and any file not in the chat triggers "Allow edits to file that has not been added to the chat?" (aider/aider/coders/base_coder.py:2191-2240). Model-suggested shell commands get the strictest form, explicit_yes_required=True (aider/aider/coders/base_coder.py:2450-2463). There is no rules engine or settings file; the deeper safety net is that every applied edit is auto-committed to git, so a bad edit is one /undo away (aider/aider/coders/base_coder.py:2375-2395).

Context and memory

Every prompt is rebuilt from a fixed ChatChunks layering — system + examples + readonly_files + repo + done + chat_files + cur + reminder (aider/aider/coders/chat_chunks.py:6-26). History is two lists, done_messages (past turns) and cur_messages (this turn); after edits apply, move_back_cur_messages shifts cur into done (aider/aider/coders/base_coder.py:1036-1046). That shift is the compaction trigger: when done-history exceeds max_chat_history_tokens — computed per model as min(max(max_input_tokens / 16, 1024), 8192) (aider/aider/models.py:355-358) — a background thread summarizes it, recursively splitting at an assistant-message boundary and keeping a verbatim tail (aider/aider/history.py:33-96).

The repo map is Aider's read-tool substitute. Rather than let the model call Read/Grep, every prompt embeds a token-budgeted map of the rest of the repo as a user/assistant message pair (aider/aider/coders/base_coder.py:750-761). RepoMap turns tree-sitter def/ref tags into a graph and runs PageRank with personalization — boosting identifiers mentioned in the conversation and references from in-chat files (aider/aider/repomap.py:470-531) — then binary-searches how many tags to include so the rendered tree fits the budget within ~15% (aider/aider/repomap.py:676-706). Durable memory is the --read read-only file (a CONVENTIONS.md, say) injected into the readonly_files chunk every prompt (aider/aider/coders/base_coder.py:478-485).

对照 Claude Code

Every organ maps to an existing page; the difference is always how it is realized.

The one organ with no Claude Code equivalent is the PageRank repo map: it does not add a tool, it replaces the read/grep tools of /stories/tools/1/ with an always-present, budgeted orientation map (aider/aider/repomap.py:470-531).

What to steal

1. The PageRank repo map. A token-budgeted map of the whole repo, always in context, kills the latency of on-demand read/grep for orientation: tree-sitter tags become a graph, PageRank ranks symbols with conversation-aware personalization (aider/aider/repomap.py:470-531), and a binary search fits the rendered tree to the budget within 15% (aider/aider/repomap.py:676-706).
2. One reflection channel with a budget and repair-grade errors. Malformed blocks, non-anchoring SEARCH sections with "did you mean" hints, lint errors, and test failures all funnel into the single reflected_message retry loop, hard-capped at 3 (aider/aider/coders/base_coder.py:924-944, aider/aider/coders/editblock_coder.py:84-124) — a uniform, bounded self-repair path instead of ad-hoc error returns.
3. Prompt-cache-first context layout. The stable-first ChatChunks order exists so cache_control markers can be pinned at chunk boundaries (aider/aider/coders/chat_chunks.py:28-55), and a daemon thread re-pings the provider to keep the cache warm between human keystrokes (aider/aider/coders/base_coder.py:1348-1392).
4. Summarize-on-format-switch — real, but not what powers the architect→editor handoff. Coder.create defaults summarize_from_coder=True (aider/aider/coders/base_coder.py:131), and when the edit format changes it summarizes away done_messages so the new model can't imitate the stale format (aider/aider/coders/base_coder.py:153-188, gate at :161) — a small contamination guard for multi-format systems. But ArchitectCoder.reply_completed explicitly sets kwargs["summarize_from_coder"] = False before building the editor coder (aider/aider/coders/architect_coder.py:32), so that gate never fires on the handoff; the editor's fresh context instead comes from a direct wipe, editor_coder.cur_messages = []; editor_coder.done_messages = [] (aider/aider/coders/architect_coder.py:38-39). The summarizer's real trigger is the /chat-mode <format> path: cmd_chat_mode leaves summarize_from_coder at its default True unless switching to "code" or "ask" (aider/aider/commands.py:191-203), whereas the /ask /code /architect /context shortcuts (_generic_chat_command) always force it False (aider/aider/commands.py:1206-1230).