> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ComposioHQ/agent-orchestrator/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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

## Installation

```bash theme={null}
# Install Aider
pip install aider-chat
# OR
pipx install aider-chat

# Verify installation
which aider
aider --version
```

## Configuration

Configure in `agent-orchestrator.yaml`:

```yaml theme={null}
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

<ParamField path="model" type="string">
  Model to use (e.g., `gpt-4-turbo`, `gpt-4`, `claude-3-opus`)
</ParamField>

<ParamField path="permissions" type="enum">
  Approval mode:

  * `skip`: Auto-approve all changes (`--yes`)
  * Other values: Prompt for approval (default Aider behavior)
</ParamField>

<ParamField path="systemPrompt" type="string">
  Custom instructions passed via `--system-prompt`
</ParamField>

<ParamField path="systemPromptFile" type="string">
  Path to system prompt file (loaded via shell command substitution)
</ParamField>

<ParamField path="prompt" type="string">
  Initial message sent via `--message` flag
</ParamField>

## How It Works

### Launch Behavior

Aider is launched with the prompt included in the command:

```bash theme={null}
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

<Accordion title="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
</Accordion>

### Auto-Commit

Aider automatically commits changes after each successful edit:

```bash theme={null}
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

```bash theme={null}
ao spawn my-project "Add error handling to API routes"
```

### Monitor Progress

```bash theme={null}
# Check status
ao status my-project/agent-123

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

### Attach to Session

```bash theme={null}
# Get attach command
ao attach my-project/agent-123

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

## Limitations

<Warning>
  Aider has limited introspection capabilities compared to other agents.
</Warning>

### 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:

```bash theme={null}
# 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

<Accordion title="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:
     ```bash theme={null}
     tmux attach -t agent-123
     ```
  2. Check if Aider is waiting for approval (if `permissions != skip`)
  3. Reduce `readyThresholdMs` in config:
     ```yaml theme={null}
     agentConfig:
       readyThresholdMs: 60000  # 60 seconds
     ```
</Accordion>

<Accordion title="Chat history file not found">
  **Cause**: Aider hasn't created the file yet, or using non-standard location

  **Solution**:

  1. Check if file exists:
     ```bash theme={null}
     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)
</Accordion>

<Accordion title="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)
</Accordion>

<Accordion title="Process detection fails">
  **Cause**: Process name doesn't match "aider"

  **Solution**: Check actual process name:

  ```bash theme={null}
  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.
</Accordion>

## 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 |

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

## Environment Variables

The plugin sets these variables:

<ParamField path="AO_SESSION_ID" type="string" required>
  Session identifier for orchestrator tracking
</ParamField>

<ParamField path="AO_PROJECT_ID" type="string">
  Project identifier (set by caller, not the plugin)
</ParamField>

<ParamField path="AO_ISSUE_ID" type="string">
  Issue/ticket identifier if applicable
</ParamField>

## Advanced Usage

### Custom Commit Messages

Aider uses auto-generated commit messages. To customize:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# .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:

```bash theme={null}
chmod +x .git/hooks/post-commit
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.