Skip to main content

​
Overview

Aider is a Python-based AI coding assistant (aider-chat package) that runs as a terminal CLI with an optional Streamlit web GUI. It provides file editing, shell command execution, web scraping, and git integration through a prompt_toolkit/rich-based REPL.
Installation: pipx install aider-chat
Binary path: ~/.local/bin/aider
Config: ~/.aider/, <git_root>/.aider.conf.yml
Version: 0.86.3.dev (Apache-2.0 license, open source)

​
Sandbox Profile

The Aider profile (profiles/60-agents/aider.sb) grants access to: 
(allow file-read* file-write*
    (home-prefix "/.local/bin/aider")
    (home-prefix "/.local/bin/aider-install")
    (home-prefix "/.aider")
    (home-literal "/.aider.conf.yml")
    (home-literal "/.aider.model.settings.yml")
    (home-literal "/.aider.model.metadata.json")
    (home-subpath "/.config/aider")
    (home-subpath "/.cache/aider")
    (home-subpath "/.local/share/aider")
)

​
Key Paths

PathPurpose
~/.local/bin/aiderpipx-installed binary
~/.aider/Main config/data directory
~/.aider/analytics.jsonAnalytics UUID + opt-in state
~/.aider/oauth-keys.envOAuth-obtained API keys (OpenRouter)
~/.aider/caches/Model pricing, version check, help index
<git_root>/.aider.input.historyReadline history (prompt_toolkit)
<git_root>/.aider.chat.history.mdMarkdown chat log
<git_root>/.aider.tags.cache.v4/SQLite-based repo map cache (diskcache)

​
Running Aider in Safehouse

​
Basic Usage

# Read-only mode (no file edits, no shell commands)
safehouse -- aider

# Allow workspace modifications
safehouse --add-dirs=$PWD -- aider

# With network for LLM API calls
safehouse --enable=network --add-dirs=$PWD -- aider

​
Shell Function Wrapper

Add to ~/.zshrc: 
aider() {
    safehouse --enable=network --add-dirs="$PWD" -- \
        ~/.local/bin/aider "$@"
}

​
Authentication

Aider stores credentials in plain files (no keychain):
MethodLocationFormat
OAuth keys~/.aider/oauth-keys.envDotenv (KEY="value")
.env files~/.env, <git_root>/.env, ./.envDotenv
YAML config.aider.conf.yml (CWD, git root, ~)YAML
Environment*_API_KEY env varsVarious

​
OAuth Flows

OpenRouter OAuth (browser + localhost callback):
  • Binds HTTP server on localhost:8484-8584
  • Opens browser to https://openrouter.ai/auth
  • Saves key to ~/.aider/oauth-keys.env
GitHub Copilot Token Exchange:
  • Exchanges GITHUB_COPILOT_TOKEN for ephemeral OpenAI key
  • Endpoint: https://api.github.com/copilot_internal/v2/token

​
Sandbox Considerations

Aider’s OAuth flow requires: 
# Enable network for OAuth callback server
safehouse --enable=network --add-dirs="$HOME/.aider" -- aider
The default sandbox blocks port binding. For OAuth, use --append-profile with a custom policy allowing network-bind.

​
Capabilities

​
LLM Tools

Aider provides these capabilities to the LLM:
  1. File editing — Whole file replacement, diff-based edits, search/replace blocks
  2. Shell commands — Via /run and /test (user-invoked, LLM suggests)
  3. Git operations — Auto-commits via GitPython
  4. Web scraping — /web command fetches URLs, optionally uses Playwright
  5. Linting — /lint runs flake8 or configured linters
  6. Voice input — /voice records audio and transcribes via OpenAI Whisper API
Aider’s /run and /test commands execute shell commands with full user privileges. The LLM can suggest commands but cannot execute them autonomously. Always review commands before running.

​
Subprocess Execution

Aider spawns subprocesses for:
ToolPurpose
gitVersion control operations
Shell commandsUser-invoked via /run and /test
pipRuntime installation of optional dependencies
flake8Python linting
System editorOpens vim/vi/notepad for /editor command
pexpectInteractive command execution (non-Windows)
Notification commandsterminal-notifier, osascript, notify-send
playwrightOptional browser automation

​
Network Access

​
Required Endpoints

EndpointPurpose
LLM API endpoints (via litellm)Chat completions (100+ providers)
https://pypi.org/pypi/aider-chat/jsonVersion check (1x/day)
https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.jsonModel pricing
https://openrouter.ai/api/v1/*OpenRouter OAuth and API
https://api.github.com/copilot_internal/v2/tokenGitHub Copilot token exchange
https://us.i.posthog.comAnalytics (PostHog)
Arbitrary URLsWeb scraping via /web command

​
Disabling Analytics

# Disable analytics before first run
aider --no-analytics

# Or set in config
echo "analytics: false" >> ~/.aider.conf.yml

​
Special Integrations

​
Streamlit Web GUI

Aider’s --gui mode launches a Streamlit web server: 
# NOT RECOMMENDED in sandbox (requires port binding)
aider --gui
Streamlit binds to localhost:8501 (default). The sandbox blocks this by default. For web GUI: 
# Custom policy allowing Streamlit port
safehouse --append-profile=<(cat <<'EOF'
(allow network-bind (local tcp "localhost:8501"))
EOF
) --enable=network -- aider --gui

​
Playwright (Web Scraping)

The /web command can use Playwright for JavaScript-rendered pages: 
pipx install aider-chat[playwright]
playwright install chromium
Playwright downloads Chromium to ~/.cache/ms-playwright/. The sandbox profile does not grant this by default. Add: 
safehouse --add-dirs-ro="$HOME/.cache/ms-playwright" \
    --enable=network --add-dirs="$PWD" -- aider

​
Configuration Files

​
Search Order (Highest Priority First)

  1. --env-file (CLI arg)
  2. ./.env (current directory)
  3. <git_root>/.env
  4. ~/.env
  5. ~/.aider/oauth-keys.env
  1. .aider.conf.yml in CWD
  2. .aider.conf.yml in git root
  3. ~/.aider.conf.yml

​
Project Files

FilePurpose
<git_root>/.aiderignoregitignore-style exclusion patterns
<git_root>/.aider.tags.cache.v4/diskcache SQLite database for repo map

​
Security Considerations

Aider has NO built-in sandboxing. All operations run with full user privileges.

​
Attack Surface

  1. Shell command execution — /run and /test commands execute with shell=True
  2. Runtime pip installs — Can download and run arbitrary Python code
  3. Clipboard polling — When --copy-paste enabled, polls every 0.5 seconds
  4. Git operations — Can modify .gitignore, git config, commit history
  5. File access — Unrestricted read/write (advisory .aiderignore)
  6. Network access — Makes requests to 10+ endpoints, arbitrary URLs via /web
  7. Analytics — PostHog enabled by default
# Minimal policy for coding tasks
safehouse \
    --add-dirs="$PWD" \
    --enable=network \
    --append-profile=<(cat <<'EOF'
; Block .git/hooks/ modification
(deny file-write*
    (subpath (string-append (param "WORKDIR") "/.git/hooks")))
; Block OAuth ports (use API keys instead)
(deny network-bind)
EOF
) -- aider "$@"

​
Troubleshooting

​
”Cannot write to ~/.aider/analytics.json”

The sandbox blocks writes outside the workspace. Disable analytics: 
aider --no-analytics
Or grant access: 
safehouse --add-dirs="$HOME/.aider" -- aider

​
“OAuth callback server failed to bind”

The sandbox blocks port binding. Use API keys instead of OAuth: 
export OPENAI_API_KEY="sk-..."
safehouse --enable=network -- aider

​
“Git operations fail”

Git requires workspace write access: 
safehouse --add-dirs="$PWD" -- aider

Build docs developers (and LLMs) love

Get started for freeTalk to us