Aider BYOK Terminal

I have been writing code since before syntax highlighting was a selling point. So when the whole industry started bolting AI onto VS Code forks with floating chat bubbles and inline ghost text, my first reaction was to close the tab. I do not want a tool that lives inside an Electron app eating two gigs of RAM to autocomplete a for loop. I want something that lives in my terminal, talks to git, and gets out of the way.

That tool, for me, is Aider. Free, open source, you bring your own API key, and it never once tried to upsell me a seat license. I pair it with Gemini 2.5 Pro because the per-task cost lands somewhere around six cents and I am not made of money. This is the setup, warts and all.

Why a terminal pair programmer and not an IDE

Here is the thing the GUI crowd never tells you: the editor is not the work. The work is the diff. Aider runs as a chat loop in your shell, you describe a change, it edits the files on disk, and it commits each change to git on its own. Every step is a commit you can read, blame, or revert. No magic buffer state, no unsaved phantom edits, no wondering what the agent actually touched.

9:48

Watch that if you have never seen it run. The first time the thing committed a clean three-file refactor and I just hit Enter on the diff, I genuinely laughed out loud at my desk. My wife asked what was funny. Hard to explain to a non-programmer that a CLI tool respecting git was the funny part.

The config: one yaml file, no GUI settings panel

Everything lives in .aider.conf.yml at the repo root, checked into git like a sane person would. This is the actual file I drop into every project. The model is Gemini 2.5 Pro, architect mode is on so it plans before it edits, and the repo map gets a budget so the model knows the shape of the codebase without me pasting files in by hand.

# Bring your own key. Set GEMINI_API_KEY in your shell, not here.
model: gemini/gemini-2.5-pro

# Plan first, edit second. The single best flag in this tool.
architect: true

# Repo map: let it learn the codebase without me spoon-feeding files.
map-tokens: 2048

# Auto-commit every change so each edit is its own reviewable commit.
auto-commits: true

# Always load my house rules into context.
read:
  - CONVENTIONS.md

# I review before I push. Do not touch the remote.
git: true
gitignore: true

The CONVENTIONS.md file is loaded read-only into every session via the read key above. This is my equivalent of a CLAUDE.md, except it is just a plain markdown file with no framework pretending it invented the idea. Keep it short. Models stop reading long house rules the same way junior devs do.

# House rules for this repo

- Use --architect mode for anything that spans more than one file.
- Cheap model, I own the keys. Do not suggest paid tiers or plugins.
- Match existing style. Read the neighbours before you write.
- No new dependencies without asking. I have buried enough node_modules.
- Write the test in the same commit as the fix, not later.
- Keep one feature per session. Reset context when the topic changes.
- Never reformat a file you were not asked to touch.

Hooks: auto-commit on edit, lint before commit

Aider handles the auto-commit itself, but I want a lint gate in front of it so garbage never lands in history. That is a plain git pre-commit hook, the oldest trick in the book. If the linter fails, the commit fails, and Aider sees the error and fixes its own mess. No special agent framework needed. Just shell.

#!/usr/bin/env bash
# Lint gate. If this exits non-zero, the auto-commit is blocked
# and Aider reads the failure and corrects course.
set -euo pipefail

staged=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.py$' || true)
[ -z "$staged" ] && exit 0

echo "pre-commit: running ruff on staged files"
ruff check $staged || {
  echo "pre-commit: lint failed, fix before commit" >&2
  exit 1
}

What a real session looks like

That is the whole loop. Add files, describe the change, read the diff, run the tests, push when I am happy. No mouse touched. My hands never leave the keyboard, which after twenty-two years is the only ergonomic argument I still care about.

The numbers, since people always ask

I will not pretend the pass rate is S-tier. It is not. On a gnarly cross-module change it sometimes plans well and then writes the wrong edit, and architect mode does not save you from that. But for the price of a vending machine snack per feature, I am not going to complain. When I want a heavier model I just swap the one line in the yaml. That is the whole point of bring your own key: the tool does not pick your model for you.

• Use --architect for anything bigger than a one-liner.
• Let the repo map do the work, stop pasting files manually.
• Keep CONVENTIONS.md short or the model skims it.
• One feature per session, then reset context so it does not drift.
• Set a spend cap in the provider console before you forget.

Read the source, not the hype

Two links worth your time. The Aider docs are genuinely good, written by someone who uses the tool. And if you want to understand the MCP plumbing behind filesystem and git access, the official catalog beats any breathless blog roundup.

Install it and stop fighting your editor

If you have a terminal and an API key, you are about ninety seconds from running this. Install with pip, export your key, run aider in any git repo, and drop the yaml above at the root. No account, no login wall, no telemetry asking for a hug.

python -m pip install aider-install && aider-install
export GEMINI_API_KEY=your_key_here
cd your-repo && aider

That is it. No subscription, no seat, no nag screen. You own the keys, you own the diffs, and the only thing between you and a commit is a linter you wrote yourself. After two decades of tools that wanted to be the center of my workflow, this one is happy being a sharp little knife. That is the highest compliment I have got.