How to Use Aider: Terminal AI Pair Programming with Git Integration

Aider is a terminal-based AI pair programming tool that edits code directly in your local Git repository. Unlike IDE-bound tools such as Cursor or GitHub Copilot, Aider runs in any terminal, works with any editor, and supports dozens of LLM providers -- from OpenAI and Anthropic to fully local models via Ollama. It reads your codebase, proposes changes as proper diffs, and auto-commits every modification with descriptive Git messages. If you have ever wanted an AI assistant that treats your repo as the single source of truth instead of a disposable scratch pad, Aider is the tool that does it.

Why Aider Matters for Web Developers

Most AI coding tools live inside a specific editor. That is fine until you need to work in Vim on an SSH session, pair with a colleague who uses a different IDE, or integrate AI assistance into a CI script. Aider sidesteps all of these constraints by operating entirely in the terminal.

Three things set it apart:

• Editor-agnostic: Aider does not care whether you use VS Code, Neovim, Emacs, or a basic terminal over SSH. It modifies files on disk and commits changes to Git. Your editor picks up the changes through normal file-watching.
• LLM-agnostic: You can point Aider at OpenAI's GPT-4o, Anthropic's Claude Sonnet, Google's Gemini, DeepSeek, Mistral, or a local model running through Ollama or LM Studio. Swap models mid-session if you want.
• Git-native by design: Every change Aider makes is an atomic Git commit with a meaningful message. Your version history stays clean, diffs are reviewable, and you can revert any AI-generated change with a single git revert.

For teams that deploy frequently, that last point is critical. A clean Git history means your deployment tool can pick up exactly what changed, when, and why -- without manually staging, committing, and writing messages yourself.

Step 1: System Requirements

Aider requires Python 3.9 or later. Most modern operating systems ship with a compatible version, but you should verify:

python3 --version

If you see Python 3.9.x or higher, you are good to go. On macOS, the system Python may be outdated -- install a current version via Homebrew (brew install python) or use pyenv for version management.

You also need Git installed and configured. Aider interacts with your repository directly, so make sure git is available on your PATH and your user identity is set:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Finally, you need API credentials for at least one LLM provider (covered in Step 3), unless you plan to run a local model.

Step 2: Install Aider

Aider offers several installation methods. Choose whichever fits your workflow.

Option A: pipx (recommended)

pipx installs Python CLI tools in isolated environments, avoiding dependency conflicts with your system Python:

pipx install aider-chat

If you do not have pipx, install it first:

# macOS
brew install pipx
pipx ensurepath

# Linux / WSL
python3 -m pip install --user pipx
python3 -m pipx ensurepath

Option B: Homebrew (macOS / Linux)

brew install aider

This handles the Python dependency automatically.

Option C: pip

A straightforward install into your current Python environment:

python3 -m pip install aider-chat

If you use this method, consider doing it inside a virtual environment to keep your global packages clean.

Option D: uv (fast Python package manager)

If you use Astral's uv tool:

uv tool install aider-chat

Verify the installation

aider --version

You should see the current version number printed to stdout. If the aider command is not found, ensure the installation directory is on your PATH.

Step 3: Configure Your AI Model

Aider supports a wide range of LLM providers. You authenticate by setting environment variables with your API keys.

OpenAI

export OPENAI_API_KEY=sk-proj-...
aider --model gpt-4o

Anthropic

export ANTHROPIC_API_KEY=sk-ant-...
aider --model claude-sonnet-4-20250514

Google Gemini

export GEMINI_API_KEY=...
aider --model gemini/gemini-2.5-pro

DeepSeek

export DEEPSEEK_API_KEY=...
aider --model deepseek/deepseek-chat

Local models via Ollama

If you prefer to keep everything on your machine:

# Start Ollama with a capable model
ollama pull deepseek-coder-v2

# Launch Aider against the local model
aider --model ollama/deepseek-coder-v2

Persisting API keys

Rather than exporting keys in every terminal session, add them to your shell profile:

# ~/.bashrc or ~/.zshrc
export OPENAI_API_KEY=sk-proj-...
export ANTHROPIC_API_KEY=sk-ant-...

Or use a .env file in your project root (add it to .gitignore):

OPENAI_API_KEY=sk-proj-...
ANTHROPIC_API_KEY=sk-ant-...

Aider reads .env files automatically when it starts.

Step 4: Start Using Aider

Navigate to any Git repository and launch Aider:

cd ~/projects/my-webapp
aider

Aider starts an interactive session in your terminal. You will see a prompt where you can type natural-language requests.

Adding files to the chat context

Aider only sees files you explicitly add to the conversation. You can add them at launch:

aider src/app.py src/models/user.py tests/test_user.py

Or add them interactively during a session:

/add src/routes/auth.py

This is intentional -- Aider works best when it has focused context rather than your entire codebase dumped into the prompt. Add the files relevant to your current task.

Asking for changes

Once files are added, describe what you want in plain English:

Add rate limiting to the /api/login endpoint. Use a sliding window
of 5 attempts per minute per IP. Return 429 with a Retry-After
header when the limit is exceeded.

Aider will propose changes as a diff, apply them to your files, and create a Git commit with a descriptive message like:

feat: Add sliding-window rate limiting to /api/login endpoint

Reviewing and undoing changes

Since every change is a commit, your standard Git workflow applies:

# See what Aider just changed
git diff HEAD~1

# Undo the last AI-generated change
git revert HEAD --no-edit

# Or undo without keeping the revert commit
git reset --hard HEAD~1

Read-only files

Sometimes you want Aider to reference a file without modifying it -- for example, a type definition file or a database schema. Use the /read-only command:

/read-only src/types/database.ts

Aider will use the file as context but will not propose changes to it.

Step 5: Core Features

Architect mode

For complex tasks, Aider offers an architect/editor workflow. The architect model (typically a stronger, more expensive LLM) designs the solution, then the editor model (a faster, cheaper LLM) implements the specific code changes:

aider --architect --model claude-sonnet-4-20250514 --editor-model gpt-4o-mini

This two-pass approach produces better results on large refactors because the architect can reason about the full plan before any code is written.

Chat modes

Aider supports multiple interaction modes you can switch between during a session:

• /code -- The default mode. Aider reads your request and edits files directly.
• /ask -- Ask questions about your codebase without making changes. Useful for understanding unfamiliar code.
• /architect -- Engage architect mode for complex, multi-file changes.

Auto-commits

By default, Aider commits every change it makes. Each commit message describes what was changed and why. This keeps your Git history granular and reviewable:

git log --oneline -5
a3f1c2d feat: Add input validation to registration form
b7e4a1f refactor: Extract email parsing into utility module
c9d2e3a fix: Handle null case in user profile serialization
d1a5b7c feat: Add rate limiting middleware to auth routes
e8f3c4d test: Add unit tests for rate limiting logic

If you prefer to review changes before committing, disable auto-commits:

aider --no-auto-commits

In this mode, Aider still applies changes to your files, but leaves them uncommitted for you to review and stage manually.

Slash commands

Aider has a rich set of in-chat commands:

Voice coding

Aider supports voice input. If you have a microphone set up, you can dictate your coding requests instead of typing them:

aider --voice

This uses OpenAI's Whisper API for transcription. It is particularly useful for describing complex changes while looking at code in a separate editor window.

Repo map

Aider automatically builds a map of your entire repository structure. This map gives the LLM an understanding of your project's architecture -- file names, class and function signatures, import relationships -- without sending the full content of every file. The repo map is what allows Aider to make targeted suggestions even for files you have not explicitly added to the chat.

You can control the level of detail:

# More detailed map (uses more tokens but gives better context)
aider --map-tokens 2048

# Disable the repo map entirely
aider --map-tokens 0

Aider auto-commits every change to Git with a descriptive message. DeployHQ auto-deploys every push -- connecting your repo to any server via SFTP, SSH, or cloud providers. Together, they create a code-to-production pipeline where your AI-generated changes hit your server in seconds. Try it free.

Step 6: Advanced Features

Configuration file: .aider.conf.yml

Create a .aider.conf.yml file in your project root (or in ~/.aider.conf.yml for global defaults) to persist your preferred settings:

# .aider.conf.yml

# Model configuration
model: claude-sonnet-4-20250514
editor-model: gpt-4o-mini

# Git behavior
auto-commits: true
dirty-commits: false
attribute-author: true
attribute-committer: false

# Context management
map-tokens: 1024
subtree-only: false

# Input/output
dark-mode: true
pretty: true
stream: true

# Code quality integration
auto-lint: true
lint-cmd: "eslint --fix"
auto-test: false
test-cmd: "npm test"

You can commit this file to your repository so the entire team shares the same Aider configuration.

Model selection strategy

Different models have different strengths. A practical approach:

• Architect model: Use the strongest model you have budget for (Claude Sonnet 4, GPT-4o, Gemini 2.5 Pro). This model does the reasoning.
• Editor model: Use a fast, cost-effective model (Claude Haiku, GPT-4o-mini). This model writes the actual code edits based on the architect's plan.

aider --architect --model claude-sonnet-4-20250514 --editor-model gpt-4o-mini

Linting integration

Aider can automatically run your linter after every code change and fix any issues it introduces:

aider --auto-lint --lint-cmd "eslint --fix src/"

Or for Python projects:

aider --auto-lint --lint-cmd "ruff check --fix ."

When a lint error is detected, Aider will attempt to fix the violation automatically before committing.

Test integration

Similarly, you can configure Aider to run your test suite after changes:

aider --auto-test --test-cmd "npm test"

If tests fail, Aider will analyze the failure output and attempt to fix the code. This creates a tight feedback loop: change code, run tests, fix failures -- all within a single interaction.

Git integration details

Aider provides fine-grained control over its Git behavior:

• --attribute-author: Sets the Git author to "aider (via LLM name)" so you can distinguish AI-generated commits in your history.
• --dirty-commits: Allow Aider to commit even when there are other uncommitted changes in the working tree. Disabled by default for safety.
• --commit-prompt: Customize the prompt Aider uses to generate commit messages.

Working with multiple files

For cross-cutting changes (like renaming an interface used across 15 files), Aider's repo map helps it find all references. Add the primary files, describe the change, and Aider will identify other files that need updating:

/add src/types/user.ts
Rename the User interface to UserProfile and update all references
across the codebase.

Aider will show you every file it plans to modify and ask for confirmation before proceeding.

Browser interface

Aider supports a browser-based interface if you prefer a GUI over the terminal:

aider --browser

This opens a chat interface in your default browser while maintaining all the same Git integration and file-editing capabilities.

Step 7: Best Practices

Be selective about which files you add

Aider works best with focused context. Rather than adding your entire src/ directory, add only the files directly relevant to your current task. If Aider needs additional files, it will ask for them or use the repo map to understand the broader structure.

A good rule of thumb: start with 1-3 files, add more as needed.

Review diffs before pushing

Even though Aider auto-commits, you should review the diffs before pushing to your remote:

# Review the last 3 Aider commits
git log --oneline -3
git diff HEAD~3..HEAD

AI-generated code is generally correct, but edge cases, security implications, and project-specific conventions deserve human review.

Use the architect-then-edit workflow for complex changes

For tasks that span multiple files or involve architectural decisions, always use architect mode:

aider --architect --model claude-sonnet-4-20250514

The architect model creates a high-level plan first, which the editor model then implements step by step. This two-pass approach significantly reduces errors on complex refactors compared to letting a single model do everything at once.

Combine Aider with your existing editor

Aider is designed to coexist with your editor. A productive workflow looks like this:

1. Open your project in your editor (VS Code, Neovim, etc.)
2. Open a terminal alongside it and run aider
3. Ask Aider to make changes -- your editor refreshes automatically
4. Review the changes in your editor's diff view
5. Continue iterating

Use /run and /test for rapid iteration

Instead of switching between Aider and another terminal to run commands, use the built-in shell integration:

/run npm run build
/test npm test

Output from these commands is shared with Aider, so if a build fails or a test breaks, Aider can immediately see the error and propose a fix.

Keep a .aider.conf.yml in your repo

This ensures consistent behavior across your team. When everyone uses the same lint command, test command, and model settings, AI-generated changes are consistent with your project standards.

Step 8: Deploy with DeployHQ

Aider's Git-native approach creates a natural synergy with deployment automation. Every change Aider makes is already a well-structured Git commit -- there is no manual staging, no forgotten files, no vague "WIP" messages. This makes the path from AI-assisted coding to production deployment remarkably short.

How the workflow fits together

flowchart LR
    A[Describe change to Aider] --> B[Aider edits files]
    B --> C[Auto-commit with descriptive message]
    C --> D[Push to remote]
    D --> E[DeployHQ detects push]
    E --> F[Build & deploy automatically]

Here is the practical flow:

1. Aider makes atomic commits: Each change is a single, well-scoped commit with a message that describes exactly what changed and why. No manual intervention needed.

2. Push triggers deployment: When you push to your remote (git push), DeployHQ detects the new commits and starts a deployment automatically (if auto-deploy is enabled for the branch).

3. DeployHQ runs your build commands: Whether your project needs npm run build, composer install, pip install -r requirements.txt, or any other build step, DeployHQ executes it on its build servers before deploying. Configure build pipelines in your project settings -- see DeployHQ build commands for details.

4. Atomic deployment: DeployHQ deploys the built output to your server via SFTP, SSH, S3, or other protocols. Atomic deployments ensure the switch from old to new code is instantaneous -- no half-deployed states.

Setting up auto-deploy for Aider workflows

In your DeployHQ project settings:

1. Connect your repository (GitHub, GitLab, Bitbucket, or any Git remote)
2. Enable automatic deployments on your target branch (e.g., main or production)
3. Configure build commands appropriate for your stack:

# Example: Node.js project
npm ci
npm run build

1. Set your server connection (SSH, SFTP, S3, DigitalOcean, AWS, etc.)

Now, every time you git push after an Aider session, the deployment pipeline fires automatically.

Example: full workflow

# Start an Aider session
cd ~/projects/my-webapp
aider src/components/Header.jsx src/styles/header.css

# Ask Aider to make a change
> Add a dark mode toggle button to the Header component.
> Use a CSS class toggle approach with prefers-color-scheme as the default.

# Aider edits the files and commits:
# "feat: Add dark mode toggle with prefers-color-scheme default"

# Review and push
git log --oneline -1
git push origin main

# DeployHQ picks up the push, runs `npm run build`, and deploys.
# Total time from request to production: under 60 seconds.

Why this beats manual deployment

• No forgotten changes: Aider commits everything it touches. You will not push a half-finished state.
• Descriptive commit history: DeployHQ shows commit messages in its deployment log, so you can see exactly which AI-generated changes are in each deployment.
• Instant rollback: If an Aider-generated change causes issues, roll back in DeployHQ to the previous deployment -- or git revert HEAD and push again.
• Branch-based workflows: Use feature branches with Aider, push to a staging branch for QA deployment, then merge to main for production. DeployHQ can deploy different branches to different servers.

Step 9: Troubleshooting

"No suitable model found" or authentication errors

Verify your API key is set correctly:

echo $OPENAI_API_KEY
# or
echo $ANTHROPIC_API_KEY

If the variable is empty, re-export it or check your .env file. Make sure the key has not expired or hit its usage limit.

Aider is not seeing my files

Aider only works inside Git repositories. If your project is not yet a Git repo:

git init
git add .
git commit -m "Initial commit"

Also confirm you have added files to the chat context with /add.

Changes are not being committed

If you see changes in your files but no Git commits:

• Check if --no-auto-commits was passed (or set in your config file).
• Verify that the Git working tree is clean enough for Aider to commit. By default, Aider will not commit if there are other dirty changes. Use --dirty-commits to override this.

High token usage or slow responses

• Reduce the repo map size: --map-tokens 512
• Add fewer files to the context
• Use a smaller/faster editor model with --editor-model
• Switch to a more cost-effective provider for routine tasks

Conflicts with your editor's auto-save

Some editors (especially with auto-format-on-save) can interfere with Aider's file writes. If you see unexpected formatting changes after Aider edits a file:

• Configure your editor to not auto-format files modified externally
• Or enable Aider's --auto-lint with your formatter as the lint command, so formatting is applied consistently

Aider modified files you did not want changed

Use the /undo command to revert the last change. For more selective reversal:

git diff HEAD~1          # See what changed
git checkout HEAD~1 -- path/to/file   # Revert specific file
git commit -m "Revert unintended change to path/to/file"

Going forward, be more specific in your requests and use /read-only for files that should not be modified.

Conclusion

Aider brings AI pair programming to the terminal without locking you into a specific editor, vendor, or workflow. Its Git-native approach -- automatic commits with meaningful messages, clean diffs, and easy reversibility -- makes it a natural fit for teams that care about code quality and deployment automation.

The combination of Aider's auto-commits with DeployHQ's automated deployment pipeline turns the feedback loop from "write code, stage, commit, push, deploy" into "describe what you want, push, deployed." If you are looking to streamline how AI-generated code reaches production, sign up for DeployHQ and connect it to the repository where you run Aider.

If you have questions about integrating Aider with your DeployHQ deployment workflow, reach out to us at support@deployhq.com or on Twitter at @deployhq.