Aider Configuration Guide

Chapter 1 - Installation Guide

macOS Installation

Method 1: Using Homebrew (Recommended)

brew install aider-chat

Method 2: Using pip

pip install aider-chat

Method 3: Using pipx (Recommended)

pipx install aider-chat

Windows Installation

Method 1: Using pip

pip install aider-chat

Method 2: Using pipx

pipx install aider-chat

Method 3: Installing from Source

git clone https://github.com/paul-gauthier/aider.git
cd aider
pip install -e .

Installation Verification

After installation, verify that Aider is successfully installed:

aider --version

---

Chapter 2 - TokenSwitch API Relay Configuration

Environment Variable Configuration

macOS/Linux Configuration

Edit the ~/.bash_profile or ~/.zshrc file:

# Write configuration
echo 'export OPENAI_API_KEY="your_token"' >> ~/.zshrc
echo 'export OPENAI_API_BASE={{apiUrl}}' >> ~/.zshrc

# Apply changes immediately
source ~/.zshrc

Windows Configuration

Execute in PowerShell:

[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "your_token", "User")
[Environment]::SetEnvironmentVariable("OPENAI_API_BASE", {{apiUrl}}, "User")

Or use system environment variables settings.

Complete Startup Parameters

Basic Startup Command

# Using Claude Sonnet 4.6 (Recommended)
aider --model cl-so-4.6

# Using Claude Haiku 4.5 (Lightweight)
aider --model cl-ha-4.5-1001

# Using other Claude models
aider --model openai/claude-3-opus-20250514
aider --model cl-ha-4.5-1001

Complete Parameter Table

Parameter	Description	Example
--model	Specify model	cl-so-4.6
--api-key	API key (optional, reads from environment variable by default)	sk-xxx
--base-url	API base URL	https://neolink.com/api/v1
--temperature	Model temperature (0-2)	0.7
--max-tokens	Maximum tokens	4096
--no-auto-commits	Disable auto commits	no value
--no-dirty	Disable dirty file prompts	no value
--voice	Enable voice input	no value
--edit	Enable edit mode	no value

Recommended Startup Command

# Basic startup (using environment variables, recommended to use Claude Sonnet 4.6)
aider --model cl-so-4.6

# Full configuration example
aider \
  --model cl-so-4.6 \
  --temperature 0.7 \
  --max-tokens 4096 \
  --no-auto-commits

# Start with specific folder
aider --model cl-so-4.6 ./src

Supported Models List

The following models can be used through TokenSwitch:

Model ID	Description
cl-ha-4.5-1001	Claude Haiku 4.5 (Lightweight, recommended for quick tasks)
cl-so-4.6	Claude Sonnet 4.6 (Balanced performance and cost, recommended)
openai/claude-3-5-sonnet-20241022	Claude 3.5 Sonnet (High performance)
openai/claude-3-opus-20250514	Claude 3 Opus (Most powerful model)
openai/gpt-4-turbo	GPT-4 Turbo version
openai/gpt-4o	GPT-4 optimized version
openai/gpt-4	GPT-4 base version

---

Chapter 3 - /add Command File Path Considerations

/add Command Basics

The /add command adds files to the current conversation context:

/add filename.py
/add path/to/file.js
/add src/components/*.vue

Path Type Explanation

Relative Paths

Relative to the current working directory:

/add utils.py              # File in current directory
/add src/main.py           # File in src folder
/add ../config/app.yaml    # File in parent directory

Absolute Paths

Full file system paths:

# macOS/Linux
/add /Users/username/project/src/main.py

# Windows
/add C:\Users\username\project\src\main.py

Wildcard Matching

Supports glob patterns:

/add src/*.py              # All Python files in src directory
/add **/*.js               # Recursively match all JS files
/add src/**/*.py           # Recursively match all Python files under src
/add tests/test_*.py       # Match files starting with test_

Windows Path Special Handling

Windows uses backslash \ as path separator:

# ✅ Correct way
/add src\models\user.py
/add C:\project\src\main.py

# Can also use forward slash (recommended)
/add src/models/user.py
/add C:/project/src/main.py

Common Path Errors and Solutions

Error	Cause	Solution
File not found	Incorrect path	Check relative path or use absolute path
Permission denied	No read permission	Check file permissions
Path too long	Windows path exceeds 260 characters	Use relative path or enable long path support
Chinese path issues	Encoding problem	Use absolute path or check system encoding

Ignore File Configuration

Create .aiderignore file in project root:

node_modules/
__pycache__/
*.pyc
.git/
.env
build/
dist/
*.log

File Loading Best Practices

1. Number of files to load at once: Recommended 5-10 files or fewer
2. File size limit: Single file recommended not exceeding 100KB
3. Priority order: Load core files first, then dependent files
4. Incremental loading: Add files gradually as needed, not loading entire project at once

---

Chapter 4 - Common Built-in Commands

File Management Commands

Command	Description	Example
/add	Add file to context	/add src/main.py
/drop	Remove file from context	/drop src/main.py
/list	List files in current context	/list
/ls	Shorthand for /list	/ls
/files	Show file list and sizes	/files

Edit and Commit Commands

Command	Description	Example
/undo	Undo last edit	/undo
/diff	View all uncommitted changes	/diff
/commit	Commit changes to Git	/commit -m "message"
/reset	Reset all changes	/reset

Session Management Commands

Command	Description	Example
/clear	Clear conversation history	/clear
/exit	Exit Aider	/exit
/help	Show help information	/help
/history	View command history	/history

Advanced Commands

Command	Description	Example
/architect	Switch to architect mode	/architect
/auto	Auto-fix all files	/auto
/lint	Run code linter	/lint
/test	Run tests	/test
/git	Execute Git commands	/git status

Special Commands

# Get help
/help              # Show all available commands
/?                 # Same as /help

# Query information
/stats             # Show token usage statistics
/version           # Show Aider version

# Switch modes
/architect         # Architect mode (more detailed planning)
/code              # Code mode (default)

---

Chapter 5 - Complete Workflow Examples

Example 1: Creating New Module

# 1. Start Aider
aider --model cl-so-4.6 src/

# 2. Add related files
/add src/models/__init__.py
/add src/models/base.py

# 3. Communicate with AI
Create a new User model with id, name, and email fields

# 4. View changes
/diff

# 5. Commit changes
/commit -m "feat: add User model"

Example 2: Refactoring Code

# 1. Add files to refactor
/add src/utils/helpers.py
/add src/utils/validators.py

# 2. Request refactoring
Extract duplicate code in these two files into common utility functions

# 3. View suggested changes
/diff

# 4. Accept and commit
/commit -m "refactor: extract common utility functions"

Example 3: Fixing Bugs

# 1. Add related files
/add src/services/auth.py
/add tests/test_auth.py

# 2. Describe the problem
User login fails with error "Invalid token", please check and fix

# 3. Run tests to verify
/test

# 4. Commit the fix
/commit -m "fix: resolve token validation issue in auth service"

---

Chapter 6 - Troubleshooting

Common Problem Solutions

Q1: Cannot Connect to API

Error: Connection refused / Cannot connect to API

Solution:

1. Check network connection
2. Verify OPENAI_API_BASE is correctly configured
3. Confirm API key is valid

# Verify environment variables
echo $OPENAI_API_KEY
echo $OPENAI_API_BASE

Q2: File Not Found

Error: File not found: xxx

Solution:

1. Check if relative path is correct
2. Test with absolute path
3. Confirm current working directory

# Check current directory
pwd

# List files
ls -la src/

Q3: Permission Denied

Error: Permission denied

Solution:

# Check file permissions
ls -l filename

# Change permissions
chmod 644 filename

Q4: Windows Path Issues

Solution:

Use forward slash instead of backslash, or use full UNC path:

# ✅ Recommended
/add src/models/user.py

# Also acceptable
/add src\models\user.py

---

Chapter 7 - Best Practices

Workflow Recommendations

1. Always use Git: Ensure all changes are in Git repository
2. Incremental file loading: Don't load entire project at once
3. Clear requirement descriptions: Provide detailed instructions rather than vague commands
4. Verify changes: Check /diff output before committing
5. Regular commits: Use meaningful commit messages

Performance Optimization

• Loading 5-10 related files at a time works best
• For large projects, have separate conversations for each functional module
• Avoid loading binary or generated files

Maximizing Effectiveness

• Provide sufficient context: Add related test and configuration files
• Use clear English descriptions for requirements
• Use /architect mode for complex refactoring
• Run /diff before Git commits to check all changes

---

Chapter 8 - Related Resources

Official Links

• Aider Official Website
• GitHub Repository
• Official Documentation

Quick Reference

Startup Command Reference

# macOS/Linux - Recommended to use Claude Sonnet 4.6
aider --model cl-so-4.6

# Windows PowerShell
aider --model cl-so-4.6

# Specify working directory
aider --model cl-so-4.6 /path/to/project

Common Commands Reference

/add file.py          # Add file
/drop file.py         # Remove file
/list                 # List files
/diff                 # View changes
/commit -m "msg"      # Commit changes
/undo                 # Undo operation
/help                 # Show help