AI AI Tools Guidebook
AI Tool Tutorials

Aider Getting Started: Terminal AI Coding With Per-Edit Git Commits

Install Aider, point it at a git repo, and run the see-diff/accept loop from your shell. No IDE, no browser, no lock-in. Updated June 2026.

Published: Updated: Author: AI Productivity Guide Team 🌐 查看中文版本

TL;DR

Aider is a free, open-source AI pair programmer that runs entirely in your terminal and edits files in your local git repo. You cd into a repo, run aider, and chat in the shell. It shows a git diff for every edit, makes one commit per accepted change, and never opens a browser. As of June 2026 it sits at roughly 41,600 GitHub stars and 5.3M+ PyPI downloads. The tool is free; you pay only for the model API you point it at (or run a local model for free). The whole point is the per-edit accept//undo loop, so this guide gets that loop running in under thirty minutes and skips the flag-by-flag manual.

What Aider actually is

Aider is a command-line program, not an IDE plugin and not a web app. The model writes file edits as diffs, Aider applies them, and each accepted edit becomes its own git commit you can roll back with /undo. Three ideas carry the whole workflow:

  • Per-edit git commits. Every accepted change is a separate commit. Bad edit? /undo reverts the last one. Your repo is the undo stack.
  • Manual context with /add and /drop. You decide which files the model sees. Aider builds a repo map of the rest but does not dump the whole tree into context.
  • Architect mode. A stronger reasoning model plans the change; a faster, cheaper model writes the actual diff. This typically costs 30-50% less than running the strong model for both passes.

Who this is for

Developers who live in a terminal: people who SSH into servers, work on machines without a GUI, or just refuse to install another Electron app. It is also a strong fit when you want the AI coding loop to be scriptable, because Aider runs headless for batch and CI jobs. If you want a graphical Composer-style experience instead, Cursor for beginners is the better starting point. For long-running agentic shell sessions, Claude Code fits better.

When to reach for it

Reach for Aider on tightly scoped changes where you want full control of context: a small refactor, adding tests for one module, fixing one specific bug. It also shines in CI-driven flows like pre-commit cleanups and scripted migrations. It loses to GUI agents on open-ended “explore the codebase and propose something” tasks, because Aider expects you to bring the relevant files in via /add rather than indexing everything for you.

Before you start

  • Python 3.8-3.13. Run python --version to confirm. The official installer ships its own isolated Python if yours is out of range.
  • A git repo with a clean working tree. Aider commits per edit; uncommitted changes get tangled with its commits and the diff becomes unreadable.
  • An API key for one provider, or a local model. Anthropic Claude is the recommended choice for code quality; OpenAI and Google work too; or run a model locally through Ollama or LM Studio for $0 in API cost.
  • A small target. Rename one function, add tests for one module, fix one bug. Not “refactor the project.”

Install Aider

The recommended path as of June 2026 is the official aider-install bootstrapper, which sets up an isolated environment automatically so nothing pollutes your system Python:

python -m pip install aider-install
aider-install
aider --version

Alternatives, all equally fine:

# isolated CLI install via pipx
pipx install aider-chat

# macOS via Homebrew
brew install aider

# uv (fast, pins Python 3.12)
uv tool install --python python3.12 --with pip aider-chat@latest

Connect a model

Set your API key as an environment variable and put it in your shell rc so it persists:

export ANTHROPIC_API_KEY=sk-ant-...
# or: export OPENAI_API_KEY=sk-...
# or: export GEMINI_API_KEY=...

Which model to pick depends on the job. For everyday edits, a fast workhorse model keeps latency and cost down; for tricky design work, run architect mode with a top reasoning model planning and the workhorse editing. Approximate API pricing per 1M tokens (in/out), as of June 2026:

ModelInputOutputBest role in Aider
Claude Sonnet 4.6$3$15Default editor and everyday edits
Claude Opus 4.7$5$25Architect (planning) model
Gemini 3.1 Pro$2$12Budget editor, large context
GPT-5.5$5$30Strong planner, capable editor
Local model (Ollama)$0$0Offline; quality below frontier

Aider tracks token spend per session, so you always see what a change cost before you keep going.

Run the loop

  1. Launch from the repo root with a specific model. Sonnet 4.6 is the safe default; add architect mode with Opus 4.7 planning for harder design tasks:
cd ~/code/myproject
aider --model anthropic/claude-sonnet-4-6 \
      --architect --editor-model anthropic/claude-sonnet-4-6
  1. Add the files you want edited. Pick the 1-5 files relevant to this task, not the whole repo:
/add src/auth/login.ts
/add src/auth/login.test.ts
  1. Ask for a small, named change in plain English. Aider replies with the proposed diff, applies it, and commits. Read the diff before you type the next prompt. That is your review window.
  2. Fix mistakes inline. /undo rolls back the last commit. /drop src/auth/login.test.ts removes a file from context. /diff shows the current diff before you commit more.
  3. Exit with /exit. Your repo now has a series of small commits, one per accepted edit. Squash them before opening the PR if you want cleaner history.

The four chat modes

You switch modes mid-session with a single command. Knowing these is most of the skill of using Aider well:

ModeCommandWhat it does
Code/codeDefault. Edits files directly to satisfy your request.
Ask/askDiscusses and answers questions about the code, never edits.
Architect/architectReasoning model plans, editor model writes the diff.
Help/helpAnswers questions about Aider itself (config, usage, errors).

A /code or /architect toggle without text flips the sticky mode for the rest of the session. The cheapest mistake to avoid is asking design questions in code mode, where Aider will start editing instead of explaining. Use /ask first, then /code once you agree on the plan.

A prompt that produces honest output

Aider works best when prompts are tight. Save this as a starting template:

You are editing files I /add'd. Constraints:
- Make the smallest change that satisfies the request.
- Do not touch files I have not /add'd. If you need another file, ASK first.
- After each edit, list the assumption it depends on in one line.
- If a test exists for the touched function, update it. If not, say "no test added; recommend adding X".

Task: [one specific change here]

The “ask before adding files” line matters. Without it, Aider will sometimes propose edits to files that are not in the chat context, which produces a diff it cannot apply cleanly.

Make it reusable

  • Save your launch command as a shell alias: alias ai='aider --model anthropic/claude-sonnet-4-6 --architect'.
  • Keep a .aider.conf.yml in the project root with model defaults, ignored paths, and the editor model. Commit it so teammates inherit the same setup. Repo-level config overrides user-level config.
  • For repeated checks, add --lint-cmd and --test-cmd so Aider runs your linter and tests and tries to fix its own breakage.
  • For CI or scripted runs, use --message "task" --yes to run non-interactively: Aider makes the edit, commits, and exits.

Common mistakes

  • /add-ing the whole repo. Aider is not an indexer; flooding context wastes tokens and produces worse suggestions. Add 1-5 files.
  • Skipping git. No git repo means no /undo and no per-edit commits, which removes the safety net entirely.
  • Running on a dirty working tree. Uncommitted changes get mixed into Aider’s commits and the diff becomes unreadable.
  • One-shot giant refactors. Architect mode helps, but the editor model still struggles with very wide diffs. Break the work into named steps.
  • Using a weak model as the architect. Plan with a strong reasoning model (Opus 4.7 or GPT-5.5) and let a fast model edit. A weak planner produces vague plans the editor cannot follow.
  • Forgetting --no-auto-commits when batching. The default commits per edit, which is great until you want to amend each change before it lands.

FAQ

  • Is Aider free? Yes. Aider itself is open-source (Apache 2.0) and free. You pay only for the model API you point it at, or $0 if you run a local model through Ollama. There is no Aider subscription.
  • Which model should a beginner start with? Claude Sonnet 4.6 as the editor is the safest default for code as of June 2026. Add architect mode with Opus 4.7 planning when a task involves multi-file design.
  • Does Aider work with local models? Yes, via Ollama or any OpenAI-compatible endpoint with --openai-api-base. Quality drops versus frontier models, but the see-diff/accept loop is identical and the API cost is zero.
  • Can I run it headless in CI? Yes. aider --message "task" --yes runs non-interactively, makes the edit, commits, and exits.
  • Why does Aider sometimes propose edits it cannot apply? Usually it referenced a file that was not in /add, or the diff format got mangled. Re-prompt with the file explicitly added.
  • Is .aider.conf.yml per-user or per-repo? Both. The repo-level file overrides the user-level one, so commit the repo file with team defaults.

External references: the official Aider documentation and the Aider polyglot leaderboard (225 Exercism exercises across C++, Go, Java, JavaScript, Python, and Rust) are the authoritative sources for current commands and model rankings.

Tags: #AI coding #Tutorial #Aider

Related Articles