How to Use Aider: The Beginner's Guide (First Install, First Edit, the Git Safety Net, and Architect Mode)

CodexFuse Team · 2026-10-31T03:57:27.257Z · 17 min read

How to Use Aider: The Beginner's Guide (First Install, First Edit, the Git Safety Net, and Architect Mode)

Learning how to use Aider comes down to one habit: you talk, Aider edits, and Git remembers. Aider is a terminal-based AI pair programmer that edits files directly in your local Git repository and commits every change with a generated commit message. Instead of copying code snippets between a chat window and your editor, you stay in the terminal, tell Aider what to change, review the diff it proposes, and let Git keep a safety net under every step.

This Aider for beginners tutorial walks the complete arc in one sitting: install Aider the right way, connect a model with an API key, open your repo, add files with /add, make your first edit, review the diff, undo safely with /undo, and switch to architect mode for bigger refactors. If you like getting oriented in a repository from the browser before you touch the terminal, GitInspect Studio chats with any GitHub repo right in your browser — a handy way to understand a codebase before Aider starts editing it.

How Do You Use Aider? The 30-Second Version

You use Aider by launching it inside a Git repository, adding the files you want changed, describing the change in plain language, and reviewing the diff before the auto-commit lands. The whole beginner loop looks like this:

1. Install with the official bootstrapper — python -m pip install aider-install, then aider-install — and confirm with aider --version.
2. Move into a clean Git repo and commit any pending work, so Aider's first change lands on a known-good baseline.
3. Launch with a model, for example aider --model sonnet --api-key anthropic=<key>, or export ANTHROPIC_API_KEY once and run plain aider.
4. Add the 1–3 files the task touches with /add; Aider's repo map already knows the rest of the repo exists.
5. Describe the change in one plain sentence, read the proposed diff, and confirm. Aider applies the edit and commits it with a generated message.
6. Something wrong? Run /undo. The last Aider commit is reversed, your files return to their previous state, and you can re-ask with better instructions.

That is the whole shape of Aider: narrow context in, reviewed diff out, one Git commit per change. The rest of this guide fills in each step.

What Is Aider, Exactly?

Aider is an open-source, terminal-based AI pair programmer that edits code in your local Git repository and commits each change automatically. It is not an IDE plugin, not a chat website, and not a hosted service: it is a Python command-line tool that sends your files to a language model you choose, applies the model's proposed edits to your files, and records each changeset as a Git commit with a sensible message. It started in 2023 as a side project by Paul Gauthier and is available under the Apache 2.0 license.

Before you ask anything, Aider builds a repo map — a compressed, tree-style summary of your entire codebase that goes into the model's context — so it knows about files you never added explicitly and can ask for them when a task needs them. That is why Aider stays useful in larger projects instead of only in single-file demos: the model sees the shape of the whole repo while you only hand it the files it should touch.

Aider works with Python, JavaScript, Rust, Ruby, Go, C++, PHP, HTML, CSS, and dozens more languages, and it does not care which editor you use — VS Code, JetBrains, Vim over SSH, or a bare terminal on a build server. It edits files on disk, so your editor simply picks up the changes through its normal file watching. If your workflow is terminal-first, that editor-agnostic design is the whole point.

How Do You Install Aider?

Install Aider with the official aider-install bootstrapper, which puts Aider in its own isolated Python environment — and even installs a separate Python 3.12 if your system Python falls outside the supported range. That isolation matters: Aider's dependencies should never fight with your project's packages.

Verify with aider --version — 0.86.2 was the current package when this guide was checked, and the number moves often, so treat your installed version as the truth. If the shell cannot find aider after installing, reopen the terminal (the bootstrapper drops a self-contained binary in ~/.local/bin, which may not be on your PATH yet) or fall back to python -m aider. Skip system package managers: Aider's own install docs warn they often install it with incorrect dependencies.

Where Does Your API Key Go?

Aider connects to a model provider you choose, and the API key lives in your environment — never in a command you screenshot, never in a file you commit. Export it once in your shell profile: export ANTHROPIC_API_KEY="your-key-here" for Claude, or export OPENAI_API_KEY="your-key-here" for OpenAI. Local models through Ollama need no key at all — just Ollama running with a model pulled.

For a one-off session you can pass the key on the command line instead, using Aider's short model aliases:

# DeepSeek
aider --model deepseek --api-key deepseek=<key>

# Claude 3.7 Sonnet
aider --model sonnet --api-key anthropic=<key>

# OpenAI o3-mini
aider --model o3-mini --api-key openai=<key>

One billing gotcha for beginners: your ChatGPT Plus or Claude Pro chat subscription does not include API access — cloud models need a separate API account with its own billing. And Aider itself costs nothing; it is open source, and you pay the model provider for the tokens you use, not Aider. Start with a small task to learn what a session actually costs before pointing a premium model at a big refactor.

How Do You Start Aider on Your Repo?

Start inside a Git repository with a clean working tree: commit everything pending first, so every Aider change lands on top of a known-good state. Aider can offer to create a repository for you, but its main review and undo safeguards assume a real Git history — an existing clean repo is the better start.

cd /to/your/project
git status   # "nothing to commit" = safe to begin
aider

Launch bare aider to let it discover the repo, or pass files up front — aider src/app.py tests/test_app.py — when you already know what the session is about. Either way, the session opens with a prompt (>) that accepts both plain-language requests and slash commands. The prompt even tells you which chat mode you are in — it reads architect> when architect mode is active — so you always know how your next message will be handled.

How Do You Make Your First Edit?

Your first edit should be deliberately small: one behavior change in one or two files, with a test or a visible check you can run yourself. The loop is /add, ask, review, accept:

1. Add the files: /add src/greeter.py — keep it to 1–3 files. The repo map already tells the model the rest of the repo exists.
2. Describe the change in one plain sentence: "Add a --shout flag that uppercases the greeting."
3. Read the proposed diff. Aider shows exactly what will change; use /diff any time to re-display the last commit's diff.
4. Confirm. Aider applies the edit and auto-commits it with a generated message.
5. Run your check: your own test command, or /run pytest inside the session — Aider can also run your lint and test suites automatically and fix what they flag.
6. Wrong? /undo. The last Aider commit is reversed and your files return to their previous state, so you can re-ask with better instructions.

Notice what never happened: you never pasted code into a chat box, and you never wondered which files the AI actually touched. Every change is a diff you saw and a commit you can reverse. That visibility is the reason developers trust Aider on real codebases.

What Are the Essential Aider Commands?

Aider's slash commands fall into four groups: files, git, models, and modes. Learn the file and git groups first — they are the whole safety story:

/web, /voice, and /paste earn their keep fast: paste a stack trace or a screenshot straight into the session instead of describing it from memory. And /run is the test-and-fix loop — run your suite, let Aider read the failures, and watch it propose the fix as a reviewed diff.

How Does the Git Safety Net Work?

Aider's safety net is ordinary Git used aggressively: every changeset becomes its own commit with a generated message, so nothing the AI does is ever more than one undo away. Start on a branch, review each diff, and you can experiment freely.

The mechanics are simple. Aider automatically commits each changeset to your local repo with a descriptive commit message — these frequent, automatic commits are the safety net, in Aider's own words. /diff shows the last commit's diff whenever you want a second look. /undo reverses the last commit Aider made, restoring your files to their previous state. And because these are real Git commits, the full Git toolbox still works: git log to see the trail, git revert to cancel a commit you already pushed, git reset --soft HEAD~1 to un-commit but keep the changes.

Two rules make the net hold. Never start Aider with uncommitted work you care about — commit first, so the baseline is clean and every Aider commit stands alone. And do the first session on a branch — git switch -c aider-first-run — so your main branch stays untouched until you merge something you have actually reviewed.

What Is Architect Mode?

Architect mode splits each coding task across two models: a strong reasoning model plans the change in plain language, and a second editor model turns that plan into precise file edits. Use it for refactors that touch several files, where asking one model to juggle planning and edit-formatting at the same time produces sloppier results.

Turn it on for one message with /architect, make it sticky with /chat-mode architect, or launch straight into it with aider --architect. The main model (--model) acts as the architect; --editor-model picks the editor, with built-in defaults if you skip it. Aider's docs are candid about the tradeoff: two models means two LLM requests per turn, so architect mode takes longer and costs more. It shines with reasoning-heavy models like OpenAI's o1 — strong at thinking through a design, weaker at emitting file edits — paired with a strong editor like GPT-4o or Sonnet.

One subtlety worth knowing: the editor model only receives the architect's last solution, not your full conversation history. So do your back-and-forth in /ask mode first — "should this be a new module or extend the existing one?" — and switch to /architect once the plan is settled. That is the mode table in miniature:

Which Model Should You Use with Aider?

Start with one of Aider's officially recommended pairings: Claude 3.7 Sonnet for the strongest editing, DeepSeek's R1 or Chat V3 for strong quality at lower cost, or OpenAI's o1, o3-mini, or GPT-4o. Aider can connect to almost any LLM — including local models through Ollama, which need no API key at all.

Model choice is a flag, not a reinstall: aider --model deepseek starts with DeepSeek, /model sonnet switches mid-session, and /models <term> searches the model list. Model names and aliases drift fast, so re-check Aider's current model guidance before committing to one — and test any candidate on a throwaway branch before trusting it with real code.

Aider vs Cursor vs Cline vs OpenCode

These four are lanes, not rivals. Aider is the terminal pair programmer, Cursor is the in-editor agent, Cline is the VS Code plan-then-act agent, and OpenCode is the terminal agent that runs ahead on its own. Pick by where you already work:

Our Cursor AI beginner guide covers the in-editor lane, the Cline beginner guide covers the plan-then-act lane, and the OpenCode beginner guide covers the terminal-agent lane. Many developers end up running two: Aider for git-disciplined pairing, something faster for throwaway edits.

How Do You Keep Aider Sessions Cheap and Safe?

Keep sessions cheap by keeping context narrow, and keep them safe by keeping Git underneath. Aider's costs are your model provider's token charges — there is no Aider subscription — so every file you /add is money and attention spent. Six habits cover both:

• 1–3 files per task. Add what the change touches; the repo map already covers the rest.
• /read-only for reference files the model must see but never touch — configs, schemas, API contracts.
• Use /ask for questions. A question round-trip costs a fraction of an editing round-trip.
• Save /architect for genuine refactors. Two models and two requests per turn is overkill for a one-line fix.
• Drive from your editor when you want to. Watch mode (aider --watch-files) lets you request edits with AI! comments and answers with AI? comments, right in your code.
• Let the auto lint/test loop run. Aider runs your linters and test suites after edits and fixes what they flag — free quality, since you were going to run them anyway.

And the standing rule from the git section: clean branch, clean tree, reviewed diffs. That discipline is the entire safety budget, and it costs you nothing.

Sources

Every fact in this guide was verified on 2026-10-30 — making this Aider tutorial current as of October 30, 2026: Aider's homepage (terminal-based AI pair programming; works best with Claude 3.7 Sonnet, DeepSeek R1 & Chat V3, o1, o3-mini, and GPT-4o; connects to almost any LLM including local models; the repo map of the entire codebase; automatic commits with sensible messages; Python, JavaScript, Rust, Ruby, Go, C++, PHP, HTML, CSS, and dozens more languages; automatic linting and testing with self-fixing; voice input; images and web pages as context; works from any IDE or editor; the web-chat copy/paste mode; the install quick start with model aliases deepseek, sonnet, and o3-mini and the --api-key flag format) at aider.chat; the installation page (aider-install accepting Python 3.8–3.13 with its own isolated environment plus an auto-installed Python 3.12 when needed; the curl and PowerShell one-liners; the uv tool install command for Python 3.8–3.13; pipx install aider-chat for Python 3.9–3.12; the pip command for Python 3.9–3.12 with a virtual-environment recommendation; the warning against system package managers; the python -m aider fallback) at aider.chat/docs/install.html; the in-chat commands reference (/add and /drop for chat context; /undo as "undo the last git commit if it was done by aider"; /diff as "display the diff of the last aider commit"; /commit for outside-the-chat edits; /git for running git commands) at aider.chat/docs/usage/commands.html; the chat-modes documentation (code as the default mode; /code, /architect, /ask, and /help as per-message commands; /chat-mode for sticky switching; the --chat-mode and --architect launch flags; the active mode shown in the prompt; architect mode's two-model design with --model as planner and --editor-model as editor, built-in editor defaults, the two-request cost, and the o1-plus-GPT-4o-or-Sonnet pairing) via aider.chat; the project history (a 2023 side project by Paul Gauthier, Apache 2.0 license) from the Aider Complete Guide; and the repo-map description (a compressed, tree-style summary of the codebase fed into the context window), the ~/.local/bin PATH note, the clean-repo recommendation, the API-account-versus-chat-subscription billing note, and the 0.86.2 current-package check cross-verified across the computingforgeeks, lachieslifestyle, enterprisedna, and spillwave guides — plus the architect-mode context note (the editor model receives only the architect's last solution, not the full history) from the community Aider modes guide. The install-method decision table, the chat-mode decision table, and the Aider-vs-Cursor-vs-Cline-vs-OpenCode comparison are original syntheses for this guide.

Frequently Asked Questions

Is Aider free to use?

Yes — Aider is open-source software, so the tool itself costs nothing. What you pay for is the model: cloud LLMs bill per token through your API account (a separate account from any chat subscription), while local models through Ollama cost nothing per token. Start with a small task to learn what a session actually costs before pointing a premium model at a big refactor.

Do I need to know Git to use Aider?

You need the basics — commit, diff, branch, and log — because Git is Aider's memory and its safety net. Aider writes the commit messages for you, and /undo reverses its own commits, but you should be comfortable checking git status and reading a diff. If Git is new to you, learn those four commands first; the rest of this guide will make much more sense.

Aider vs Cursor — which should a beginner choose?

Choose by where you work, not by hype. If you live in the terminal or over SSH and want every AI change recorded as a Git commit, Aider's lane fits. If you iterate fast inside one editor and want an agent that edits on demand, the in-editor lane fits. They solve different problems, and plenty of developers use both.

Can I use Aider with local models instead of an API?

Yes. Aider connects to local models through Ollama, which needs no API key — you just need Ollama running with a model pulled. Local models keep your code on your machine and cost nothing per token, at the price of weaker editing quality than the frontier cloud models. It is a solid way to learn Aider's workflow before spending anything on API calls.

Will Aider work over SSH or without an IDE?

That is exactly its home turf. Aider is a plain terminal program — it runs over SSH, in tmux, or on a build server with no graphical editor at all, and it is editor-agnostic when you do have one. Watch-files mode even lets you drive it from your editor by writing AI! and AI? comments in your code. If your workflow is terminal-first, Aider removes the copy-paste loop that IDE-bound tools still impose.