AI AI Tools Guidebook
AI Tool Tutorials

Aider — Terminal-First AI Coding Without the Browser

Pip install, point it at a repo, and run the see-diff/accept loop from your shell — no IDE, no browser, no lock-in.

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

What this covers

A working terminal-first AI coding loop with Aider in under thirty minutes. Aider is a CLI tool — you cd into a git repo, run aider, and chat in your shell while the tool shows you a git diff for every edit, commits each accepted change, and never opens a browser. This guide is about getting that loop running, not about every flag in the manual. The pain it solves: people install Aider, paste their API key, ask for a refactor, see a wall of diff hunks, and bail without realizing the whole point is the per-edit accept/reject flow.

Key concepts:

  • Per-edit git commits: every accepted change is its own commit you can /undo.
  • /add and /drop: you control the chat context manually — Aider doesn’t index everything.
  • Architect mode: a planning pass with a stronger model before the editor model writes code.

Who this is for

Developers who live in a terminal, run servers via SSH, work on machines without GUIs, or just refuse to install an Electron app for everything. Also a strong fit if you want the AI coding loop to be scriptable — Aider runs in headless mode for batch jobs. If you want a graphical Composer-style experience, Cursor for beginners is a better starting point.

When to reach for it

Use Aider for tightly scoped changes where you want full control of context — small refactors, adding tests, fixing a specific bug. Also for CI-driven flows: pre-commit cleanups, scripted migrations. It loses to GUI agents on “explore the codebase and propose” tasks, because Aider expects you to bring the files in via /add. For agentic long-running shell sessions, Claude Code is a better fit.

Before you start

  • Python 3.10+ available. python --version to confirm.
  • A git repo with a clean working tree. Aider commits per edit; uncommitted changes will get tangled with its commits.
  • An API key for at least one provider: Anthropic (recommended for code), OpenAI, or a local model via Ollama / LM Studio.
  • A small target picked: rename one function, add tests for one module, fix one bug. Not “refactor the project.”

Step by step

  1. Install with pip. Use a virtualenv or pipx to avoid polluting the system Python:
pipx install aider-chat
# or: pip install aider-chat
aider --version
  1. Set your API key as an env var. Put it in your shell rc so it persists:
export ANTHROPIC_API_KEY=sk-ant-...
# or: export OPENAI_API_KEY=sk-...
  1. From the repo root, launch Aider with a specific model. Sonnet 4.6 is the safe default for code edits; Opus 4.7 for architect mode on tricky 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 Aider to edit with /add. Don’t dump the whole repo — pick the 1-5 files relevant to this task:
/add src/auth/login.ts
/add src/auth/login.test.ts
  1. Ask for a small, named change in plain English. Aider will reply with the proposed diff, apply it, and commit. Read the diff before pressing enter on the next prompt — that is your review window.
  2. If the change is wrong, /undo rolls back the last commit. If a file no longer belongs in context, /drop src/auth/login.test.ts removes it. If you want to see the current diff before committing more, /diff.
  3. When done, /exit. Your repo has a series of small commits, one per accepted edit. Squash before opening the PR if you want a cleaner history.

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.
- 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 aren’t in chat context, which produces broken diffs.

Quality check

  • Every commit message Aider wrote is readable and accurate. If not, edit them with git commit --amend before pushing.
  • The diff for each commit is small enough that a reviewer could read it in under two minutes.
  • Tests pass after each commit, not only at the end. Run them between Aider turns for non-trivial changes.
  • No files outside /add were touched. Verify with git log --stat.
  • Architect mode produced a plan you could actually follow, not just vague “consider refactoring” text. Tighten the architect prompt if not.

How to reuse this workflow

  • Save your common aider 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 setup.
  • For repeated tasks (running tests, formatting), add --lint-cmd and --test-cmd flags so Aider can verify its own changes.
  • Use --message for one-shot non-interactive runs from CI — Aider makes the edit, commits, exits.

/add the files → state a tight change → review the diff → accept or /undo → repeat → /exit → squash if needed.

Common mistakes

  • /add-ing the whole repo. Aider isn’t an indexer; flooding context wastes tokens and gets you worse suggestions.
  • Skipping git. Aider needs a git repo; without one you lose /undo and per-edit commits.
  • Running on a dirty working tree. Your uncommitted changes get mixed into Aider’s commits and the diff becomes unreadable.
  • Asking for huge refactors in one turn. Architect mode helps but the editor model still struggles with very wide diffs — break it up.
  • Using GPT-5.4 for architect mode. Use GPT-5 or Opus 4.7 for planning, and a faster model for editing.
  • Forgetting --no-auto-commits when you want to batch reviews. Default Aider commits per edit, which is great until you want to amend before each one.

FAQ

  • Does Aider work with local models?: Yes, via Ollama or any OpenAI-compatible endpoint with --openai-api-base. Quality drops vs. frontier models but the loop is identical.
  • Can I run it headless in CI?: Yes — aider --message "task" --yes runs non-interactively and exits.
  • Why does Aider sometimes propose edits I can’t apply?: Usually it referenced a file not in /add, or its diff format got mangled. Re-prompt with the file explicitly added.
  • Is .aider.conf.yml per-user or per-repo?: Both — repo-level overrides user-level. Commit the repo file with team defaults.

Tags: #AI coding #Tutorial #Aider

Related Articles