Aider Agent Plugin

Run Aider AI pair programming tool with git commit-based activity detection

The Aider agent plugin integrates the Aider AI pair programming tool into Agent Orchestrator, providing a simple, git-aware agent with auto-commit functionality.

Overview

Aider is an AI pair programming tool that automatically commits changes to git. The plugin:

• Launches Aider with prompt delivered inline
• Detects activity by monitoring git commits and chat history
• Uses Aider’s auto-commit feature to track completed work
• Supports one-shot and interactive modes

Aider focuses on simple, git-integrated workflows. It lacks session introspection and metadata tracking compared to Claude Code or Codex.

Installation

# Install Aider
pip install aider-chat
# OR
pipx install aider-chat

# Verify installation
which aider
aider --version

Configuration

Configure in agent-orchestrator.yaml:

plugins:
  agent: aider

projects:
  - name: my-project
    path: ~/code/my-project
    agentConfig:
      model: gpt-4-turbo
      permissions: skip
      systemPrompt: "You are a helpful coding assistant."

Configuration Options

model · string

Model to use (e.g., gpt-4-turbo, gpt-4, claude-3-opus)

permissions · enum

Approval mode:

• skip: Auto-approve all changes (--yes)
• Other values: Prompt for approval (default Aider behavior)

systemPrompt · string

Custom instructions passed via --system-prompt

systemPromptFile · string

Path to system prompt file (loaded via shell command substitution)

prompt · string

Initial message sent via --message flag

How It Works

Launch Behavior

Aider is launched with the prompt included in the command:

aider --model gpt-4-turbo --yes --message "Fix type errors"

Unlike Claude Code (which delivers prompts post-launch), Aider receives the prompt at startup.

Activity Detection

The plugin uses two signals to detect activity:

1. Recent Git Commits: Checks if any commits were made in the last 60 seconds
2. Chat History Mtime: Monitors .aider.chat.history.md modification time

Activity state classification

Condition	State	Timestamp
Process not running	exited	Now
Commits in last 60s	active	Now
Chat history < 30s old	active	Chat mtime
Chat history < threshold	ready	Chat mtime
Chat history > threshold	idle	Chat mtime
No chat history	null	—

Default threshold: 30 seconds

Auto-Commit

Aider automatically commits changes after each successful edit:

git log --since="60 seconds ago" --format=%H

The plugin uses this to detect recent activity without needing JSONL session files.

Usage Examples

Spawn an Agent

ao spawn my-project "Add error handling to API routes"

Monitor Progress

# Check status
ao status my-project/agent-123

# View git history
cd /path/to/workspace
git log --oneline -10

Attach to Session

# Get attach command
ao attach my-project/agent-123

# Manually attach (tmux runtime)
tmux attach -t agent-123

Limitations

Aider has limited introspection capabilities compared to other agents.

No Session Info

Aider does not expose structured session data. The plugin returns null for:

• getSessionInfo(): No summaries, token counts, or cost tracking
• getRestoreCommand(): No native resume support

No Metadata Updates

Unlike Claude Code and Codex, Aider does not automatically update session metadata. You must manually track PRs and branches:

# Manually update metadata after creating PR
ao metadata set my-project/agent-123 pr https://github.com/user/repo/pull/123

Limited Activity Detection

Activity detection relies on git commits and file mtime:

• Long-running tasks without commits appear idle
• Chat history updates are less granular than JSONL events
• No distinction between “ready” and “waiting for input” states

Troubleshooting

Agent shows 'idle' but is still working

Cause: Aider hasn’t made a commit or updated chat history recently

Solution:

1. Attach to session to check actual status:
   tmux attach -t agent-123
   
2. Check if Aider is waiting for approval (if permissions != skip)
3. Reduce readyThresholdMs in config:
   agentConfig:
     readyThresholdMs: 60000  # 60 seconds
   

Chat history file not found

Cause: Aider hasn’t created the file yet, or using non-standard location

Solution:

1. Check if file exists:
   ls -la /path/to/workspace/.aider.chat.history.md
   
2. Wait for Aider to make its first API call (file is created lazily)
3. Verify Aider is running with chat history enabled (default)

No cost or token usage data

Cause: Aider does not expose this data

Solution: Track costs manually via:

• OpenAI/Anthropic billing dashboard
• Shell history parsing (if using API keys with per-request tracking)
• Aider’s built-in cost reporting (if available in CLI output)

Process detection fails

Cause: Process name doesn’t match “aider”

Solution: Check actual process name:

ps aux | grep -i aider

If Aider is installed as aider-chat or similar, the detection regex may fail. The plugin searches for the substring “aider” in the command line.

Comparison with Other Agents

Feature	Aider	Claude Code	Codex	OpenCode
Provider	Aider.chat	Anthropic	OpenAI	OpenCode
Auto-commit	✅ Yes	❌ No	❌ No	❌ No
Session Files	Markdown	JSONL	JSONL	SQLite
Cost Tracking	❌ None	✅ Full	✅ Full	❌ None
Auto-metadata	❌ None	✅ PostToolUse	✅ PATH wrappers	❌ None
Resume Support	❌ None	✅ Native	✅ Native	❌ None
Activity Detection	⚠️ Git commits + mtime	✅ JSONL events	✅ File mtime	❌ None
Best For	Simple git workflows	Enterprise features	OpenAI ecosystem	Experimental

Use Aider for simple, git-integrated workflows. For production deployments with cost tracking and metadata updates, use Claude Code or Codex.

Environment Variables

The plugin sets these variables:

AO_SESSION_ID · string · required

Session identifier for orchestrator tracking

AO_PROJECT_ID · string

Project identifier (set by caller, not the plugin)

AO_ISSUE_ID · string

Issue/ticket identifier if applicable

Advanced Usage

Custom Commit Messages

Aider uses auto-generated commit messages. To customize:

# In agent workspace, after Aider commits
git commit --amend -m "feat: Add error handling to API routes"

Manual Chat History Parsing

Chat history is stored in Markdown format:

# View recent chat
tail -50 .aider.chat.history.md

# Search for errors
grep -i error .aider.chat.history.md

Integration with Git Hooks

Leverage Aider’s auto-commit with git hooks:

# .git/hooks/post-commit
#!/bin/bash
# Notify orchestrator of new commits
ao metadata set $AO_SESSION_ID last_commit "$(git rev-parse HEAD)"

Make executable:

chmod +x .git/hooks/post-commit