Aider

Aider is a terminal-based pair‑programming tool that lets you edit code alongside an LLM, with git integration and a lightweight UI that stays out of your way. It matters when you want to iterate on code using natural‑language prompts without leaving the terminal—especially for refactoring, boilerplate generation, or exploring a codebase where switching between an editor and a chat interface would break flow. Aider records every change in git, auto‑generates commit messages, and keeps a persistent conversation history in a hidden .aider/ directory so you can resume sessions or inspect what the model did at any point.

Starting a repository

To begin working in a directory, run:

aider .

If you want to target specific files, list them after the command:

aider src/main.py utils/helpers.py

The first invocation creates a .aider/ project directory that stores the conversation log, edit history, and a default configuration file (~/.aider.conf.yml for global defaults, or a project‑level .aider.conf.yml override). Aider reads the OPENAI_API_KEY or ANTHROPIC_API_KEY environment variable to authenticate; if neither is present it exits immediately with:

Error: no API key found for provider openai

(or the equivalent for Anthropic). Setting the key once in your shell or .bashrc/~/.zshrc is sufficient for the session.

One‑off edits with --message

When you don’t need an interactive session, use the --message flag to send a single prompt and exit:

aider --message "add a timeout guard around the database connection" src/db.py

Aider applies the change, commits it with an LLM‑generated message (e.g., aider: add timeout guard around db connection), and exits. If you want to preview the change before it’s committed, pair --message with --no-auto-commit:

aider --message --no-auto-commit "rename auth variable to user_token" src/auth.py

The tool will print the diff and wait for you to approve or reject it before any git operation occurs.

Configuring model and behavior

Aider’s default model is gpt-4o, but you can override it per‑invocation or globally:

aider --model claude-3-5-sonnet .

Global defaults live in ~/.aider.conf.yml:

model: gpt-4o
temperature: 0.2

Project‑level .aider.conf.yml takes precedence for that repository. The model key accepts any model identifier supported by the chosen provider (e.g., gpt-4o, gpt-4-turbo, claude-3-5-sonnet, claude-3-opus-20240229). The temperature key controls randomness; Aider passes it directly to the provider’s API.

Environment variables can override config keys. For example, setting ANTHROPIC_API_KEY and using --base-model lets you switch the underlying provider for a given session without editing config files:

aider --base-model claude-3-5-sonnet .

The --base-model flag is distinct from --model; the former tells Aider which provider’s API to route the request through, while the latter selects the specific model version. Confusing the two—passing a model name that the base provider doesn’t support—produces:

Error: model 'gpt-4o' not found in your current Anthropic plan

rather than the expected edit.

Git integration and commit workflow

Aider’s hallmark is seamless git interaction. After each edit cycle it stages the changed files and creates a commit whose message follows the pattern aider: <your prompt’s intent>. If your team enforces conventional commits or stricter message formats, you can amend the generated message post‑hoc or use a pre‑commit hook to rewrite it.

To avoid automatic committing—useful when you’re testing a series of edits or working in a CI‑safe environment—use --no-auto-commit. When you’re ready, stage and commit manually:

aider --no-auto-commit .

git add .
git commit -m "refactor: extract validation logic per aider suggestions"

If a merge conflict arises because the repo state diverged from Aider’s expectations, the tool marks the conflict in the file and prints:

Conflict detected in src/index.js. Resolve manually, then run `aider --resume .` to continue.

After you resolve the conflict in your editor, --resume re‑reads the file, reconciles the remaining conversation history, and proposes the next edit.

Sharp edges and failure modes

• Context‑window overflow. Each LLM has a finite context window. When the accumulated conversation history plus the current file contents exceed that limit, Aider silently drops the oldest conversation turns. You’ll notice the model asking about code it “already saw” or repeating earlier suggestions. The warning sign is a gradual degradation of edit quality rather than a hard error, though exceeding the absolute maximum triggers:

  Error: maximum context length exceeded

In that case, trim the conversation log with aider --delete-log . or reduce the number of files passed on the command line.

• Rate‑limiting from the provider. If you hit a provider’s RPM limit, Aider returns the provider’s HTTP status text:

  Error: 429 Rate limit exceeded

The tool then backs off and retries with exponential back‑off, but rapid successive invocations without pausing can accumulate delays. Throttling is best handled by your shell or a wrapper script.

• Model‑provider mismatch. Supplying a model that doesn’t belong to the active provider (e.g., gpt-4o while ANTHROPIC_API_KEY is set) yields:

  Error: provider openai not configured for model gpt-4o

or the reverse. The fix is to ensure the env var matches the --model/--base-model choice, or to set the appropriate key before invoking Aider.

• --message vs. interactive session loss. Running aider --message "add logging" applies one edit and exits. The next time you run a separate --message command, Aider starts a fresh session with no memory of the previous edit unless you’ve committed and the repo state is stable. Novices often run:

  aider --message "fix indentation"
  aider --message "rename function"

in quick succession, only to find the second edit conflicts with the first because the file’s state changed between calls. For multi‑step workflows, prefer the interactive mode aider . which maintains history in .aider/ between prompts.

• Auto‑commit message format. Aider’s default commit messages omit a type: prefix (e.g., refactor:), which some repositories reject via pre‑commit hooks. You can customize the template by setting the commit_template key in .aider.conf.yml:

  commit_template: "aider: %s"

but this key is not documented in all Aider releases; using an unsupported key results in a startup error:

  Error: unknown config key commit_template

Stick to keys confirmed in the version you’re running, or accept the default and amend messages afterward.

Cleanup and teardown

When you’re done with a project, the .aider/ directory contains the full conversation log. To reset state and discard history:

rm -rf .aider

This removes the session but leaves your file edits uncommitted—ensure you’ve either committed desired changes or reverted them first.

To purge only the conversation history while keeping any committed edits, run:

aider --delete-log .

This deletes the in‑memory chat log but preserves the .aider/ directory structure and any git commits already made.

If you want to remove Aider from a machine entirely, simply delete the binary (usually placed in /usr/local/bin/aider or ~/.local/bin/aider depending on how it was installed) and optionally unset any AIDER_* environment variables you may have added to your shell profile. No system services or daemons are installed, so a simple which aider followed by rm $(which aider) is sufficient.

Key takeaways

• aider . starts an interactive session; aider --message "prompt" performs a single edit and exits.
• Model selection uses --model for the version and --base-model for the provider; mismatched choices produce immediate provider‑specific errors.
• Git auto‑commit can be suppressed with --no-auto-commit; conflicts are marked and require manual resolution before --resume continues.
• Context‑window limits cause silent truncation; exceeding the absolute maximum yields Error: maximum context length exceeded.
• API‑key absence is the most common startup failure, producing Error: no API key found for provider openai.
• Config lives in ~/.aider.conf.yml (global) or project‑level .aider.conf.yml; unrecognized keys cause startup errors.
• The tool is lightweight—no background processes, no installed services—making it easy to drop in and out of workflows without teardown overhead.

This page was rewritten on 14 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.