Aider for Commit-Driven AI Coding Sessions

Aider is an open-source, terminal-based AI coding assistant that edits files directly inside a local Git repository, and the thing that separates it from the crowded field of AI coding tools is not the quality of its code generation. It's that every edit an AI model makes lands as its own discrete, reviewable Git commit. Paul Gauthier started the project in 2023 as a side project; it now runs under an Apache 2.0 license, has drawn hundreds of contributors, and carries no venture-backed pressure to wall off features behind an enterprise sales team. The numbers back up that it's used daily by a serious population of engineers, not treated as a novelty: over 49,000 GitHub stars, more than 5.7 million PyPI installs, and something like 15 billion tokens processed. None of that matters as much as the underlying architectural choice, though. In Aider, Git is the state machine the entire workflow runs on. It's the state machine the entire workflow runs on.

How Aider's automatic commit behavior works during a session

Every time Aider successfully applies an edit, it commits that edit immediately, with a commit message the AI itself writes to describe what changed and why. Every time Aider successfully applies an edit, it commits that edit immediately, with a commit message the AI itself writes to describe what changed and why, and it is not optional by default. It's not optional by default.

Dirty-file handling is a companion behavior worth understanding before anything else. If a file already has uncommitted changes sitting in the working tree, Aider commits those first, under their own message, before it touches the file with an AI-generated edit. Human edits and AI edits end up in distinct, attributable commits rather than tangled together in one indistinguishable diff, because separation keeps them from being tangled together. Human edits and AI edits end up in distinct, attributable commits rather than tangled together in one indistinguishable diff.

The payoff appears in git log the moment you run it. Instead of the familiar mess of "wip," "fix stuff," and "more changes" commit messages that developers write when they're moving fast, the log reads like an actual changelog, one entry per AI action, each with a rationale attached. You can disable this with --no-auto-commits, and a handful of users do. But the default is the opinionated choice, and it's the one that makes the rest of Aider's design make sense.

Structuring a session: files to add, protect, and branch

Aider builds context for the model in layers, and the priority order matters. At the top sits the system prompt and edit-format instructions, fixed for the session. Below that is read-only context: the repository map, any files loaded with /read, and a conventions file if one exists. At the bottom, and the only layer the model is actually permitted to modify, is read-write context, made up of files explicitly added with /add.

That's the whole trick to controlling what Aider can touch: controlling what's in scope controls what can end up in a commit. /add, /drop, and /read-only are the commands that do this work, and using them deliberately, rather than dumping an entire repo into context, is most of what separates a clean session from a chaotic one.

A few Git-native commands operate mid-session on top of this: /commit, /undo, and /diff. /undo /undo is the one to remember under pressure. It runs a git reset --hard against the last Aider-authored commit, leaving human-made commits untouched. One keystroke, and the last AI change disappears cleanly, without dragging your own work down with it.

Teams that use Aider heavily tend to converge on a branching convention: work happens on a dedicated aider/<topic> branch, and it merges back to main only after review. That habit turns experimentation into something closer to free. If the branch goes sideways, you throw it away. Nothing lost.

The repository map: how Aider gives the LLM codebase awareness without dumping every file into context

Feeding an entire codebase into an LLM's context window is expensive and, past a certain size, simply impossible. But feeding it too little is worse: the model starts making changes that break dependencies it never saw. Aider's answer to this tension is what it calls the repository map.

Under the hood, Aider runs Tree-sitter over each source file and applies language-specific tag queries that pull out two categories of information: def tags, covering definitions like functions, classes, and methods, and ref tags, covering the places those names get used elsewhere in the codebase. For languages where Tree-sitter's queries only surface definitions and not references (C++ is a noted example), it falls back to Pygments tokenization to backfill the missing reference data.

From there, Aider treats the codebase as a graph, files as nodes, dependency relationships as edges, and runs a ranking algorithm similar in spirit to PageRank to figure out which parts of that graph matter most to the task at hand. Whatever ranks highest fills the available token budget. The map gives the model structural awareness of the whole repo without ever loading the whole repo.

Edit formats and the Coder system: matching the edit type to the commit's risk level

The Coder system, a modular engine responsible for orchestrating the back-and-forth between the LLM, the file edits it proposes, and the Git commits that follow, underlies Aider's interface and produces that orchestration directly. Different "coder" variants exist for different edit formats, and the format you choose changes the shape of the risk you're taking on.

Four formats cover most use: the diff format (handled by EditBlockCoder) applies surgical, line-level edits and is the default for routine work, carrying the lowest risk of a bad apply. The whole-file format rewrites entire files and suits small, tightly scoped files where a diff would just add noise. udiff applies unified-diff-style precision for targeted changes. And architect mode, covered on its own below, splits planning from execution across a multi-step process.

Switching between them doesn't require restarting the session: /chat-mode <format> swaps the format on the fly. A common pattern is to work in diff mode for ordinary changes, jump into architect mode when a gnarly refactor shows up, then drop back to diff for the cleanup edits that follow. Choosing the wrong format for the job has a real cost: whole-file rewrites on a 2,000-line module produce commits that are miserable to review, blown up far past what the actual change required. Matching format to task is really a way of keeping every commit an appropriate, reviewable size.

Architect mode: splitting reasoning from execution across two models and two commit stages

A model sharp enough to plan a clean six-file refactor will, in the same breath, generate a patch with broken syntax that Aider can't even apply, a pattern that occurs constantly in LLM-assisted coding. Reasoning quality and reliable edit-format output don't always come from the same model, and architect mode exists because of that mismatch.

The mode splits the work across two models and two stages. An architect model, Claude Opus 4 being a commonly cited example, handles the planning: what needs to change, how the pieces fit together, why. It's a role that leans on reasoning quality and doesn't burn many tokens doing it. An editor model, Claude Haiku 4.5 in the same example, then takes that plan and turns it into actual file edits, a role optimized for clean, dependable output at volume. Nothing requires the two models to come from the same provider.

The economics work out in Aider's favor more often than not. One high-end model tier is expensive per token; a cheaper, faster model tier handles high-volume edit generation cheaply. Running the split configuration frequently costs less for a full session than running the expensive model on every single step, while producing better results on the hard parts. That said, architect mode isn't free of overhead, and for a simple, single-file tweak, the two-stage handoff isn't worth invoking. It earns its keep on multi-file refactors, structural changes, and anything that qualifies as a real rewrite of logic, where it measurably cuts down on failed edits.

CONVENTIONS.md and.aider.conf.yml: making session behavior consistent and version-controlled

Anyone who used early AI coding assistants remembers the specific annoyance of a model that ignored house style entirely, reaching for whatever library or naming pattern it had seen most in training, regardless of what the rest of the codebase actually did. The output worked, technically, and looked like it came from somewhere else.

Aider's fix is a file called CONVENTIONS.md, loaded as read-only context, that spells out the team's actual standards: use httpx instead of requests, enforce strict type hints, whatever the project cares about. It loads either with the --read CONVENTIONS.md flag at startup or with /read mid-session. When prompt caching is available, the conventions file can be cached, which keeps long sessions faster and cheaper rather than re-sending the same conventions on every single request.

.aider.conf.yml, sitting at the project root, is the same job for session configuration rather than coding style. Model choice, the architect/editor split, and other defaults live in that file, committed to version control alongside the code itself. Every person on the team who runs that coding assistant on that repo inherits the same setup automatically, no team chat message required to keep everyone aligned.

Watch mode and AI! comments: staying in the editor while Aider commits in the background

Running Aider in watch mode makes it start monitoring files in the repo for specially marked comments that trigger actions or questions. It's a different way of talking to the tool that doesn't require ever touching the terminal.

The two triggers do different things. A comment marked for action tells Aider to make the described change, which produces an edit and, following the standard behavior, a commit. A comment marked as a question asks Aider for a response instead, without triggering file edits. The workflow this enables is straightforward: stay in VS Code, or JetBrains, or Vim, or whatever editor is already open, drop a comment describing what needs to happen, save the file, and let Aider pick it up. No alt-tabbing to a terminal, no copying file paths, no re-explaining context that's already sitting right there in the code.

Nothing about the underlying commit behavior changes here. An AI! comment still runs through Aider's normal edit cycle and produces the same kind of atomic, individually-described commit as typing the instruction directly into the Aider prompt would. Watch mode changes how the instruction gets in. It doesn't touch what comes out the other side.

Voice input, /web, and /run: the supplementary input channels and their interaction with the commit loop

Aider also accepts voice input, recording audio through sounddevice, showing a live level meter while it listens, and transcribing the result through a speech-to-text service. It's a reasonable fit for longer, conversational instructions, something like "rename handleClick to handleSubmit and update the parent component to match" comes out faster spoken than typed, and Whisper's transcription is generally clean enough that fixing the occasional error is quicker than retyping the whole instruction. It needs a decent microphone and a quiet room, which makes it a much better fit for a home office than a shared one.

/web gives Aider a way to pull outside context into a session: point it at a URL, and it scrapes the page so the model can use that documentation or API reference before it writes an edit. Both of these are input channels sitting alongside the main chat prompt. Neither one changes the commit loop itself; they just change what information reaches the model before it acts.

Model selection and the Aider Polyglot benchmark: choosing what runs inside the commit loop

Aider tracks performance across more than 70 models on a public leaderboard, and swapping which one runs a given session takes a single /model command, no restart needed. Given how much the architect/editor split depends on picking the right model for each role, that kind of low-friction swapping is close to the point. It's close to the point.

The benchmark behind that leaderboard, called Aider Polyglot, tests models against 225 of the hardest exercises pulled from a pool of 697 available on Exercism, spread across C++, Go, Java, JavaScript, Python, and Rust. What makes it different from most model benchmarks is that it scores a model inside Aider's actual edit loop, applying real patches to real files, rather than grading isolated text completions. Spreading the benchmark across six languages maintains meaningful separation between models that plan well and models that also edit reliably, which is, after all, the exact distinction the rest of Aider's design is built around.