Skip to content
,

Aider Guide (2026): AI Pair Programming in Your Terminal With Claude, GPT or Ollama

9–13 minutes
Surprised woman in a maroon hoodie holding an AIDER card at a tech conference, hook text: AI codes in your terminal

Aider is a free, open-source AI pair programmer that runs in your terminal. You tell it what to change in plain English, and it edits the files in your project directly, then commits each change to git with a sensible message so you can review or undo it in seconds.

It works with almost any model: Claude, GPT, Gemini and DeepSeek through their APIs, or fully local models through Ollama, so your code never leaves your PC. It also builds a map of your whole codebase, which is why it copes well with real projects rather than single files.

This guide covers installing Aider on Windows, Mac and Linux, connecting a cloud API or a local Ollama model (including the context-size trap that ruins most local setups), the commands you will use every day, chat modes, config files and fixes for common errors.

Details come from the official Aider docs and GitHub repo, checked in November 2026.

TL;DR

  • Install: python -m pip install aider-install then aider-install (Python 3.8-3.13), or the one-line installer for your OS.
  • Run with Claude: cd your-project, then aider --model sonnet --api-key anthropic=YOUR_KEY.
  • Run with DeepSeek: aider --model deepseek --api-key deepseek=YOUR_KEY.
  • Run locally: start Ollama with OLLAMA_CONTEXT_LENGTH=8192 ollama serve, then aider --model ollama_chat/<model>.
  • Daily commands: /add, /drop, /ask, /architect, /undo, /run, /test.
  • Safety net: every edit is a git commit; /undo reverts the last one.

What Is Aider?

Aider describes itself as “AI pair programming in your terminal”. You run it inside a git repository, add the files you want to work on, and chat. The model proposes edits, Aider applies them to your files, and it commits the result.

Feature What it does
Repo map Builds a compact map of your whole codebase so the model understands how files connect
Git integration Auto-commits each change with a message; diff, review and undo with normal git tools
100+ languages Python, JavaScript, TypeScript, Rust, Go, C++, PHP, HTML, CSS and many more
Lint and test Runs your linter and tests after edits and can fix what fails
Images and web pages Add screenshots or docs pages as context
Voice Speak your requests instead of typing
Editor watch mode Write instructions as code comments in your IDE and Aider acts on them
Any LLM Cloud APIs or local models via Ollama and other OpenAI-compatible servers

Aider itself is free. You only pay for API usage if you use a paid model, and local models cost nothing beyond your electricity.

Install Aider

The official docs recommend the aider-install helper, which puts Aider in its own environment (and can install Python 3.12 for it) so it does not clash with your other Python projects.

  1. Make sure Python is installed (python --version). aider-install works with Python 3.8 to 3.13.
  2. Run python -m pip install aider-install
  3. Run aider-install
  4. Open a new terminal and check it works: aider --version
Other install options Command
Mac and Linux one-liner curl -LsSf https://aider.chat/install.sh | sh
Windows PowerShell one-liner powershell -ExecutionPolicy ByPass -c "irm https://aider.chat/install.ps1 | iex"
uv uv tool install --force --python python3.12 --with pip aider-chat@latest
pipx (Python 3.9-3.12) pipx install aider-chat

The docs advise against installing Aider through system package managers (apt, brew formulae from third parties and so on), because they often bring the wrong dependencies. You also need git installed, since Aider works inside git repos.

Use Aider With Claude, GPT, Gemini or DeepSeek

Go into your project folder and start Aider with a model alias and your API key:

Provider Command
Anthropic (Claude Sonnet) aider --model sonnet --api-key anthropic=YOUR_KEY
DeepSeek aider --model deepseek --api-key deepseek=YOUR_KEY
OpenAI aider --model o3-mini --api-key openai=YOUR_KEY (GPT-5 family models are also supported)
Google Gemini aider --model gemini --api-key gemini=YOUR_KEY
OpenRouter aider --model openrouter/<provider>/<model> with OPENROUTER_API_KEY set

Aliases such as sonnet, opus, haiku and gemini point to current models and get updated in new releases. To avoid typing keys every time, put them in a .env file or .aider.conf.yml (see below), or set environment variables like ANTHROPIC_API_KEY.

Need a key? See our guides to getting a Claude API key and getting a DeepSeek API key. For which Claude model codes best, read best Claude model for coding.

Use Aider With Local Models (Ollama)

Running Aider with a local model keeps your code completely private. The setup is simple, but there is one trap you must avoid.

  1. Install Ollama and pull a coding model: ollama pull <model>. A Qwen coder model is a common choice; pick the largest that fits your VRAM. Our Ollama guide shows how.
  2. Tell Aider where Ollama is. Mac/Linux: export OLLAMA_API_BASE=http://127.0.0.1:11434. Windows: setx OLLAMA_API_BASE http://127.0.0.1:11434, then open a new terminal.
  3. Start Ollama with a bigger context window: OLLAMA_CONTEXT_LENGTH=8192 ollama serve (on Windows, set OLLAMA_CONTEXT_LENGTH as an environment variable and restart Ollama).
  4. In another terminal, go to your project and run aider --model ollama_chat/<model>.

The trap: the Aider docs warn that Ollama’s default context window is only about 2k tokens, and that Ollama silently throws away anything that does not fit. That means the model never sees most of your files and gives strange, broken edits with no error message.

By default, Aider now asks Ollama for enough context to fit each request plus 8k tokens for the reply. To force a fixed size for a model, add this to .aider.model.settings.yml in your home folder or project:

- name: ollama_chat/<model>
  extra_params:
    num_ctx: 65536

Use the ollama_chat/ prefix, not ollama/; the docs recommend it. Be realistic too: small local models edit code far less reliably than top cloud models. A 30B-class coder on a 24 GB GPU is a sensible minimum for serious work, and you can always switch models mid-session with /model.

Your First Session

  1. Open a terminal in your project folder. If it is not a git repo yet, Aider offers to create one.
  2. Start Aider with your model, for example aider --model sonnet.
  3. Add the files you want changed: /add app.py utils.py (or pass them on the command line: aider app.py utils.py).
  4. Ask for a change in plain English: Add input validation to the signup function and return a clear error message for each invalid field.
  5. Aider shows the edits, applies them and makes a git commit.
  6. Review with /diff. Not happy? Type /undo.
  7. Run your tests from inside Aider: /test pytest. If they fail, Aider sees the output and can fix it.

Essential Commands

Command What it does
/add <files> Add files Aider may edit
/read-only <files> Add files for reference only
/drop <files> Remove files to free context
/ask <question> Ask about the code without editing
/code <request> Request code changes (default mode)
/architect <request> Plan with one model, edit with another
/diff Show changes since your last message
/undo Revert the last commit Aider made
/run <cmd> or !<cmd> Run a shell command and optionally share output
/test <cmd> Run tests; output is added only if they fail
/web <url> Scrape a page into the chat as markdown
/model <name> Switch the main model
/tokens See how much context you are using
/clear and /reset Clear history; reset also drops all files
/commit Commit edits you made outside Aider
/ok Tell Aider to go ahead with a proposed change
/help <question> Ask about Aider itself
/exit Quit

Chat Modes: Code, Ask, Architect

Mode Use it for
Code (default) Making changes to files
Ask Understanding code, planning, reviewing without touching files
Architect Bigger changes: an “architect” model plans, an “editor” model writes the edits
Context Letting Aider work out which files are relevant

Switch with /chat-mode, or prefix a single message with /ask or /architect. A good habit: discuss the plan in /ask, then say /code go ahead once you agree.

Config Files and Conventions

  • .aider.conf.yml in your home folder or repo root sets defaults (model, auto-commits, lint and test commands) so you can just type aider.
  • .env holds API keys like ANTHROPIC_API_KEY. Keep it out of git.
  • .aider.model.settings.yml sets per-model options such as Ollama’s num_ctx.
  • Conventions file: write your coding rules (style, libraries to use, test framework) in a markdown file such as CONVENTIONS.md and load it with /read-only CONVENTIONS.md or aider --read CONVENTIONS.md. Our AGENTS.md guide explains how to write rules files that AI coding tools follow.
  • Turn off auto-commits with --no-auto-commits if you prefer to commit yourself.

Use Aider From Your Editor

Start Aider with --watch-files and keep coding in VS Code, JetBrains, Vim or any editor. Add a comment that ends in AI! to ask for a change, for example # add retry logic with exponential backoff AI!, and save.

Aider spots it and makes the edit. A comment ending in AI? asks a question instead.

Tips for Better Results

  • Add only the files that need changing. The repo map gives the model the bigger picture; too many added files waste context and money.
  • Make small, specific requests. “Add a –dry-run flag to the export command” beats “improve the CLI”.
  • Set lint and test commands (--lint-cmd, --test-cmd, --auto-test) so Aider fixes its own mistakes.
  • Use architect mode for refactors that touch many files.
  • Check /tokens on long sessions and /drop or /clear when it grows large.
  • Work on a branch so you can throw away an experiment in one command.

Troubleshooting

Problem Likely cause Fix
aider not found Install path not on PATH yet Open a new terminal; rerun aider-install
Local model gives nonsense edits Ollama context too small, prompt silently cut Start Ollama with OLLAMA_CONTEXT_LENGTH=8192 or set num_ctx
“Model not recognised” warning Unknown or misspelled model name Check the name; for Ollama use ollama_chat/
Edits fail to apply Model is weak at the edit format Use a stronger model or architect mode
Authentication error Wrong or missing API key Check --api-key, .env or environment variables
Dependency conflicts after pip install Installed into a shared Python Use aider-install, uv or pipx instead
High API bills Too many files added, long chats Drop files, clear history, use a cheaper model for simple tasks
Aider changed the wrong thing Vague request /undo, then ask more specifically

Aider vs Other AI Coding Tools

Tool Type Pick it if
Aider Open-source terminal pair programmer You want any model, local support and git-first workflow
Claude Code Anthropic’s agentic CLI You use Claude and want a more autonomous agent
Gemini CLI / Codex CLI Vendor CLIs You are tied to Google or OpenAI
Cursor AI code editor You prefer a full IDE over the terminal

Aider’s core releases have slowed compared with 2024-2025, but the main branch keeps adding support for new Claude, GPT and Gemini models. It remains one of the most flexible free options, especially for local models.

My Take

Aider is the tool I would recommend to anyone who wants AI coding help without being locked into one vendor. The git-commit-per-change design makes it safe to experiment, and the same commands work whether you plug in Claude or a local model on your own GPU.

Start with a strong cloud model to learn the workflow, then try a local coder model through Ollama for private projects. Just remember to raise Ollama’s context size first.

FAQ

Is Aider free?

Yes. Aider is open source and free. You pay only for API usage if you use paid models.

Can Aider work offline?

Yes, with a local model through Ollama or another local OpenAI-compatible server.

Which model is best for Aider?

Top cloud models like Claude Sonnet or Opus, GPT-5 models and DeepSeek give the most reliable edits. Aider publishes leaderboards on its website comparing models.

Why does Aider work badly with Ollama?

Usually because Ollama’s default context is about 2k tokens and it silently drops the rest. Start Ollama with OLLAMA_CONTEXT_LENGTH=8192 or higher.

How do I undo an Aider change?

Type /undo to revert the last commit Aider made, or use normal git commands.

Does Aider need git?

Yes, it works inside git repos and offers to create one if needed. You can turn off auto-commits with –no-auto-commits.

Can I use Aider in VS Code?

Yes. Run Aider in the VS Code terminal, or start it with –watch-files and write comments ending in AI! in your code.

What languages does Aider support?

Over 100, including Python, JavaScript, TypeScript, Rust, Go, C++, Java, PHP, HTML and CSS.

Sources

Free weekly email

Get new AI guides every week

One short weekly email with our newest local AI, ComfyUI and AI tool guides. No spam, no pop-ups, just the good stuff.

Free. Unsubscribe anytime in one click. We only use your email to send this newsletter. See our privacy policy.

Surprised woman in a maroon hoodie holding an AIDER card at a tech conference, hook text: AI codes in your terminal