One piece of advice from that page deserves quoting whole: if Aider is hopelessly stuck, code the next step yourself and then hand the work back to it. You rarely meet documentation that openly suggests doing part of the job for the tool.

Another from the same place: if it is stuck, change models - switching between different models often gets past the problem.

Git Integration

The second thing Aider did before others and that everyone now expects.

Changes are committed automatically, with a sensible message. From then on you work with familiar Git commands: diff, revert, read the history. There is no custom undo mechanism layered on top - just an ordinary repository.

The code's defaults are: auto-commits on, committing a dirty tree on, Git usage on. So by default the tool assumes you are in a repository and that committing is allowed.

Linting and Tests

Here the README and the code disagree, and the difference is worth knowing.

The README promises: automatically lint and test your code every time Aider makes changes, and Aider can fix what the linters and test suites find.

The code's defaults are different: automatic linting is on, automatic test running is off. Tests are run by command or enabled through configuration separately.

The practical conclusion is simple: the linter runs itself after edits, the tests do not until you say so.

Creating New Files

A small thing every newcomer trips over.

Ask Aider to create a new file and it may not see it. The documentation gives a direct instruction: add the file to the repository first with /add <file>, and then Aider will know that file exists.

The reason is structural: files matching Git's ignore rules or Aider's own exclusion file are skipped.

Installation

It installs unusually - through a separate installer rather than directly.

The split is not accidental. The package itself is called aider-chat and requires Python from 3.10 up to 3.14. The installer is a separate package that requires Python from 3.8 and installs Aider through uv under Python 3.12, installing that itself if the system lacks it. It works on macOS, Linux and Windows.

Then you change into the project directory and launch with a model and a key:

Configuration lives in .aider.conf.yml, in the home directory or the repository root. One caveat in the sample config matters: only OpenAI and Anthropic keys may live in the YAML itself; keys for every other API go in .env.

A Benchmark of Its Own

Another thing Aider did before most: its own harness for comparing models, sitting right in the repository.

The tasks come from Exercism exercises, and the scoring is end-to-end: a natural-language request becomes executable code, the code lands in files, and the tests either pass or they do not. Not a similarity score - works or does not.

It is stated separately that the harness must be run inside a Docker container, because the generated code executes without human review. A fitting warning, and unfortunately a rare one.

The model leaderboards on the project's site grew out of this, and the industry cited them for a long time.

The Percentages Aider Wrote About Itself

The release notes carry a recognisable line: Aider wrote 88 percent of the code in this release. Other releases say 92, 87, 72 percent. A badge with that number sits in the README header too.

There is no method behind those figures in the notes: how the share was calculated is not stated. It is a self-report, not a measurement, and deserves to be read that way - as a curiosity rather than an argument.

What to Know in Advance

The repository map does not see everything. Two things are recorded in open issues: Git submodules are excluded from the map with only a warning, and dependencies - particularly private and niche ones - do not make it into the map at all, which the issue's author links to hallucinated APIs and an infinite tailspin.

There is no call-level view. The map shows signatures but not call-stack or method-level dependency analysis. That is an open proposal, not a delivered feature.

Python 3.13 support is an open issue. The package declares a range up to 3.14, but the 3.13 issue is not closed.

Two packages, two different requirements. aider-chat needs Python 3.10 or newer; the aider-install installer needs 3.8 or newer. They are separate packages and their requirements should not be conflated.

Do not add the language counts together. The README says a hundred-plus languages, while one release added 130 languages with linter support and 20 with repo-map support. Those are different counters and cannot be summed.

First-Encounter Mistakes

Installing aider-chat directly. The official route is the installer, which sorts out the Python version for you.

Dumping many files into the conversation. The documentation warns outright that irrelevant code distracts and confuses the model.

Expecting tests to run automatically. Linting is on by default; tests are not.

Asking it to create a file without adding it. /add first, then the request.

Keeping every provider's keys in the YAML. Only OpenAI and Anthropic belong there; the rest go in .env.

Running the benchmark harness outside a container. It executes generated code unreviewed, and the authors ask you not to.

Treating the release percentages as a measurement. There is no method behind them.

Counting on current model support. The list of recommended models in the README stayed in 2025, and there has been no release for a year.