Step 1: Install Aider (2 Minutes)
Aider is a terminal-based AI pair programmer that works directly with your git repository. Installation: pip install aider-chat (or pipx install aider-chat for isolated installation). Verify: aider --version. Aider runs in your terminal — no IDE required. It reads and edits files, creates git commits, and works with any editor. For developers who prefer terminal workflows: Aider is the most natural AI coding tool.
API key setup: Aider supports multiple AI providers. Set your API key as an environment variable: ANTHROPIC_API_KEY for Claude, OPENAI_API_KEY for GPT-4, or GEMINI_API_KEY for Google models. Aider auto-detects the available keys. Default model: Claude Sonnet (best balance of quality, speed, and cost for Aider's workflow). Override with: aider --model claude-opus-4-20250514 for complex tasks.
First run: navigate to your project directory. Run: aider. Aider starts an interactive session in the terminal. It reads the git repository, understands the file structure, and is ready for prompts. Type your first request: 'Add a health check endpoint to the Express server.' Aider edits the file and shows the diff. Type /commit to create a git commit with a descriptive message. AI rule: 'Run Aider from the project root (the git repository root). Aider uses git to track changes — it must be in a git repo to function.'
Step 2: Configure Aider for Your Project (3 Minutes)
Configuration file: create .aider.conf.yml in your project root. This file configures Aider's behavior: model selection, auto-commit preferences, file inclusion/exclusion patterns, and conventions. Example: model: claude-sonnet-4-20250514, auto-commits: true (Aider commits after each change), lint-cmd: npx eslint --fix (run linter after each edit), test-cmd: npx vitest run (run tests after each edit).
Conventions file: Aider reads a conventions file that provides project-specific instructions (similar to CLAUDE.md). Create CONVENTIONS.md in the project root. Content: the same project context, coding conventions, and testing standards as CLAUDE.md. Aider reads this file and follows the conventions when generating code. Reference it in .aider.conf.yml: read: [CONVENTIONS.md].
You can also use CLAUDE.md directly — Aider supports reading any markdown file as context. If you already have a CLAUDE.md: reference it in .aider.conf.yml with read: [CLAUDE.md]. No need to maintain a separate conventions file. AI rule: 'Reuse your existing CLAUDE.md with Aider. One source of truth for conventions across all AI tools.'
If you already have a CLAUDE.md (for Claude Code) or .cursorrules (for Cursor): reference it in .aider.conf.yml with read: [CLAUDE.md]. Aider reads it as context for every prompt. No need to create a separate CONVENTIONS.md with duplicate content. One source of truth: works for Aider, Claude Code, Cursor, and any other tool that reads markdown instructions. Update once, all tools benefit.
Step 3: The Aider Terminal Workflow
Adding files to the session: Aider only edits files that are 'in the chat.' Add files with /add src/routes/users.ts or start Aider with specific files: aider src/routes/users.ts src/services/user-service.ts. Aider can read (but not edit) other files for context. Add read-only files with /read-only src/types/user.ts. AI rule: 'Add the files you want Aider to edit. Add related files as read-only for context. Aider's edits are more accurate when it has context from related files.'
The edit-test-commit cycle: (1) Describe the change: 'Add pagination to the GET /users endpoint with page and pageSize query parameters.' (2) Aider edits the files and shows the diff. (3) If you configured test-cmd: Aider runs the tests automatically. If tests fail: Aider can attempt to fix them. (4) If auto-commits is on: Aider creates a git commit with a descriptive message. If off: you review and commit manually. This cycle: code → test → commit — happens in seconds.
Multi-file editing: Aider handles multi-file changes naturally. Add all relevant files to the session. Describe the feature: 'Create a new orders module with: Drizzle schema, service functions, API route, and Vitest tests.' Aider creates or edits all files, running tests after each change. Git commits: one per logical change, with descriptive messages. AI rule: 'For multi-file features: add all target files to the session before describing the feature. Aider generates better code when it can see all related files simultaneously.'
Common mistake: describe the feature first ('Create a new user service'), then add the files. Aider: does not know which files to edit because they were not in the session. It may create new files with different naming than your convention or miss existing patterns. Better: /add src/services/user-service.ts src/routes/users.ts src/tests/users.test.ts THEN describe the feature. Aider: sees the existing file structure and patterns before generating code.
Step 4: Advanced Aider Features
Architect mode: for complex changes, use Aider's architect mode (--architect flag or /architect command). Architect mode: uses a more capable model (Opus) to plan the changes, then a faster model (Sonnet) to implement them. The architect: decides which files to edit and what changes to make. The editor: implements the changes. This two-model approach: produces better results for complex multi-file features. AI rule: 'Use architect mode for features that touch 5+ files or require architectural decisions. For single-file changes: standard mode is faster and cheaper.'
Lint integration: configure lint-cmd in .aider.conf.yml. After every edit: Aider runs the linter. If the linter reports errors: Aider automatically fixes them. This ensures: every edit produces lint-clean code. Combined with your conventions file: Aider generates code that follows your rules AND passes your linter. AI rule: 'Always configure lint-cmd. Aider's lint integration is one of its strongest features — it catches formatting and pattern issues that the conventions file might miss.'
Git integration: Aider creates one commit per logical change with a descriptive message. The git history: clean, granular, and easy to revert. If a change is wrong: git revert the specific commit. Aider's commit messages follow conventional commit format by default. Override with your project's format in the conventions file. AI rule: 'Aider's git integration is its superpower for terminal developers. Every change: committed, described, and revertible. The git log becomes a narrative of the development session.'
Every Aider edit: one git commit. Message: descriptive, following conventional commit format. A session that creates a new feature across 4 files: 4 focused commits, each revertible independently. If the third commit introduced a bug: git revert that specific commit. The other 3 changes: untouched. This granularity: impossible with manual development (developers batch changes into large commits). Aider's commit-per-change: makes the git history a development narrative.
Aider Setup Summary
Complete Aider setup checklist.
- Install: pip install aider-chat. Verify: aider --version. Runs in terminal, no IDE needed
- API key: ANTHROPIC_API_KEY (Claude), OPENAI_API_KEY (GPT-4). Auto-detected from environment
- Config: .aider.conf.yml in project root. Model, auto-commits, lint-cmd, test-cmd
- Conventions: CONVENTIONS.md or reuse CLAUDE.md. Referenced in config with read: [CLAUDE.md]
- Files: /add for editable files, /read-only for context files. Add before describing the task
- Workflow: describe change → Aider edits → tests run → auto-commit. Seconds per cycle
- Architect mode: Opus plans, Sonnet implements. For complex multi-file features
- Git: one commit per change. Descriptive messages. Clean history. Easy revert