How Aider works under the hood

Codex and Aider may appear similar on the surface, but their inner workings are fundamentally different. In Codex, the model possesses tools and actively explores the repository, while Aider operates without any tools. The harness determines what the model perceives, the model responds in plain text, and the harness extracts and applies the necessary edits from that text. This article delves into a single message's journey through Aider's Python source, mirroring the approach used for Codex in a previous analysis.

The structure of Aider revolves around the main() function, which creates a single Coder and iterates on coder.run(). Each edit format corresponds to a distinct Coder subclass, complete with its own prompts and parser. Changing the edit format, such as transitioning from /ask to /architect, does not require any flag changes. Instead, the SwitchCoder class takes over, prompting the main function to build a new Coder from the old one, preserving shared files, history, and cost (via Coder.create()).

If the edit format changes, the previous history is summarized to prevent confusion, as the new LLM might attempt to imitate the outdated format, potentially disobeying the system prompt.

The model's input is carefully organized by ChatChunks, following a specific order: system prompt, examples, read-only files, repository map, past history, editable files, the current turn, and finally, the edit-format rules reminder. Stable elements are placed at the beginning, while volatile components are positioned at the end, ensuring the prompt cache retains a lengthy prefix for optimal performance.

The editable files follow the history, allowing the model to access the most recent version of a file directly alongside the request.

Aider simulates context blocks as conversation, utilizing invented "Ok." messages from the assistant between actual messages. A history summary is presented in the same manner as a user message, beginning with "I spoke to you previously about..." (generated by summarize_all in aider/history.py and summary_prefix in aider/prompts.py).

The model treats these summaries as regular user messages, not as internal notes. The entire conversation is forwarded to litellm, an API that accommodates multiple providers at temperature 0 by default. Retryable errors back off from 0.125 seconds, doubling the delay until it reaches 60 seconds.

Notably, Aider does not employ tools, as the base class sets functions = None, and reflection is disabled (num_reflections = 0, max_reflections = 3). Three coders previously attempted to use JSON function calls for editing, but they have been removed from the registry. The decision to forgo functions stems from early experiments indicating a 3.5% decrease in coding competence when using such methods.

Consequently, edits are represented as fenced text, and Aider identifies them using regular expressions. The sole exception is a fenced bash block within the reply, which, when prompted, executes only if the user explicitly permits it. The output of this bash block is integrated into the subsequent turn, rather than being directly returned to the model.

This distinction alters the concept of "agentic" behavior. While Codex continues looping until the model ceases requesting tools, Aider's loop revolves around reflection. After each turn, if Aider detects a problem, it returns the issue as the next user message, limited to a maximum of three reflections (max_reflections = 3). The four criteria for identifying a problem include an edit that deviates from the expected format or behavior.