ai-dispatch (aid)

aid is a Multi-AI CLI Team Orchestrator written in Rust. It lets a human dispatcher or a primary AI such as Claude Code delegate work to multiple AI CLI tools, track progress, inspect artifacts, enforce methodology, and iterate through one consistent interface.

Licensed under the MIT License.

Why aid?

Without an orchestrator, a multi-agent CLI workflow breaks down fast:

• Managing multiple AI CLIs is chaotic because every tool has different flags, output formats, and calling conventions.
• No unified progress visibility means background work is mostly blind until a process exits.
• No cost tracking across tools makes token usage and spend hard to monitor over time.
• Manual worktree management for parallel code tasks adds friction to every implementation run.
• No methodology enforcement means prompt discipline, testing standards, and review habits drift between agents.

Quick Start

Prerequisites

Install Rust (1.85 or later, required for edition 2024) and whichever AI CLIs you want aid to orchestrate. aid auto-detects supported agents on your PATH: gemini, codex, opencode, cursor, kilo, codebuff, and auto.

Install

# From crates.io (recommended)
cargo install ai-dispatch

# Or one-liner
curl -fsSL https://aid.agent-tools.org/install.sh | sh

Then run the interactive setup wizard:

aid setup

This detects installed agents, configures your OpenRouter API key (for aid query), and shows your ready-to-use configuration.

Install From Source

cargo install --path .

Setup for Claude Code

aid ships with a recommended Claude Code prompt that enables orchestrator-first workflows. Copy it into your project or global CLAUDE.md:

# Project-level (recommended)
cat claude-prompt.md >> CLAUDE.md

# Or global (applies to all projects)
cat claude-prompt.md >> ~/.claude/CLAUDE.md

See claude-prompt.md for the full recommended prompt with agent selection guide, batch file format, and completion notification pattern.

If you want an isolated state directory while testing:

export AID_HOME=/tmp/aid-dev

First Research Task

Run a lightweight research task and write the answer to a file:

aid run gemini "Summarize the design principles in DESIGN.md" \
  -o /tmp/aid-design-summary.md

For quick ad hoc exploration, use aid ask:

aid ask "How does the retry flow work in this repo?"

First Coding Task

Dispatch a coding task into its own git worktree and ask aid to verify automatically:

aid run codex "Document the MCP server workflow in README.md" \
  --dir . \
  --worktree docs/mcp-readme \
  --verify auto

Watch, Inspect, Iterate

Track progress while the agent runs, then inspect the artifacts:

aid watch --tui
aid board --today
aid show t-1234
aid show t-1234 --diff
aid retry t-1234 --feedback "Tighten the configuration example and keep it source-accurate."

Run With Auto Agent Selection

Let aid choose the best available agent using its task classifier and capability matrix:

aid run auto "Create a responsive settings UI for the usage dashboard" --dir .
# [aid] Auto-selected agent: cursor (reason: frontend task (medium) → cursor (score: 9))
# [aid] Auto-selected model: auto (complexity: medium)

auto classifies each prompt into one of eight task categories — research, simple-edit, complex-impl, frontend, debugging, testing, refactoring, documentation — estimates complexity (low/medium/high), then scores every installed agent against a capability matrix. The best-scoring agent wins, with adjustments for budget mode, rate limits, and historical success rates.

The model tier is auto-selected based on complexity: low → cheap/free models, medium → standard, high → premium.

Core Concepts

Agents

An agent is the CLI backend that actually performs work. aid normalizes command construction, logging, usage extraction, and completion handling behind one adapter trait.

Examples:

aid run gemini "Compare SQLite and Postgres for local task state" \
  -o /tmp/storage-notes.md

aid run codex "Implement retry-aware board filtering" \
  --dir . \
  --worktree feat/board-filter

aid run opencode "Rename TaskRow to BoardRow in src/board.rs" \
  --dir .

aid run cursor "Refine the TUI layout for narrow terminals" \
  --dir .

aid run codebuff "Refactor the auth module into separate files" \
  --dir .

aid run auto "Explain the best agent for a multi-file refactor in this repo" \
  --dir .

Tasks

Every dispatch becomes a tracked task with a stable ID like t-1234. Tasks can run in the foreground, in the background, or as retries with feedback.

Examples:

aid run codex "Add MCP schema regression tests" \
  --dir . \
  --bg \
  --worktree feat/mcp-tests

aid watch t-1234

aid retry t-1234 \
  --feedback "The parser still fails on framed messages. Reproduce first and add coverage."

aid run codex "Harden transient subprocess handling" \
  --dir . \
  --retry 2 \
  --verify auto

Workgroups

Workgroups are shared context containers. Create a workgroup once, then dispatch multiple tasks that inherit the same background constraints and notes.

Examples:

aid group create dispatch \
  -c "Repo rules: English docs only, keep diffs minimal, prefer source-backed claims."

aid run gemini "Summarize open design questions in DESIGN.md" \
  --group wg-a3f1 \
  -o /tmp/open-questions.md

aid run codex "Update README.md with the orchestrator workflow" \
  --group wg-a3f1 \
  --dir . \
  --worktree docs/readme

aid watch --group wg-a3f1
aid board --group wg-a3f1
aid group show wg-a3f1

Agent Memory

Project-scoped persistent knowledge that auto-injects into agent prompts. Four types:

• Discovery — bug patterns, API behaviors, gotchas
• Convention — code style, naming, architecture decisions
• Lesson — what worked/failed (30-day TTL)
• Fact — versions, configs, endpoints

aid memory add discovery "Auth module uses bcrypt not argon2"
aid memory list --type convention
aid memory search "auth"
aid memory update m-a3f1 "Auth now uses argon2 after migration"
aid memory forget m-a3f1

Shared Findings

Workgroup-scoped ephemeral evidence for investigation collaboration. Agents emit [FINDING] tags in their output, which are auto-captured and injected into subsequent task prompts within the same workgroup.

# Manual posting
aid finding add wg-abc1 "gamma can be zero in tricrypto pool"

# Agent auto-capture: any agent output containing [FINDING] is saved
# Example agent output: "[FINDING] WBTC as input causes all outputs to panic"

# List findings
aid finding list wg-abc1

# Findings also appear in workgroup summaries
aid summary wg-abc1

Fast Query (v5.8)

Instant LLM queries via OpenRouter — no agent subprocess startup. Two tiers:

# Free tier (default) — $0, uses openrouter/free
aid query "What does gamma=0 mean in CryptoSwap?"

# Auto tier — paid, OpenRouter selects best model
aid query --auto "Explain this error trace"

# Explicit model
aid query -m google/gemini-2.0-flash-001 "Summarize this"

# Save response as workgroup finding
aid query "Key insight about pool state" -g wg-abc1 --finding

Configure models and API key via aid setup or ~/.aid/config.toml:

[query]
free_model = "openrouter/free"
auto_model = "openrouter/auto"
api_key = "sk-or-v1-..."

Workspace Isolation (AID_GROUP)

Set AID_GROUP to automatically scope all commands to a workgroup without passing --group everywhere:

export AID_GROUP=$(aid group create my-feature -c "Feature implementation context")

aid run codex "Implement the parser" --dir . --worktree feat/parser
aid run codex "Add parser tests" --dir . --worktree feat/parser-tests
aid board          # only shows tasks in this group
aid watch --quiet  # only watches tasks in this group
aid merge --group  # merges all done tasks in this group

Worktree Management

aid manages git worktrees for parallel conflict-free task execution. Worktrees can be created automatically with --worktree or managed explicitly:

# Explicit worktree lifecycle
WT=$(aid worktree create feat/my-feature)
aid run codex "Implement feature" --dir $WT
aid run codex "Add tests" --dir $WT
aid worktree list
aid worktree remove feat/my-feature

# Automatic worktree (created per-task)
aid run codex "Implement feature" --worktree feat/my-feature --dir .

aid merge auto-merges the worktree branch into the current branch and cleans up the worktree directory. Failed tasks auto-cleanup their worktrees. Worktree escape detection warns if an agent accidentally modifies the main repo.

Codebuff Plugin (Optional)

codebuff is an optional agent that requires separate installation. It bridges the Codebuff SDK to aid's event protocol via a Node.js wrapper.

# 1. Install the plugin
cd plugins/codebuff && npm install && npm install -g .

# 2. Get an API key at https://www.codebuff.com/api-keys
export CODEBUFF_API_KEY=cb-pat-...

# 3. Add to your shell profile to persist across sessions
echo 'export CODEBUFF_API_KEY=cb-pat-...' >> ~/.zshrc

# 4. Run a task
aid run codebuff "Refactor the auth module" --dir .

The plugin outputs codex-compatible JSONL events, so aid show, aid watch, and the TUI work seamlessly. If CODEBUFF_API_KEY is not set, aid will show setup instructions instead of failing silently.

Cost note: Codebuff SDK v0.10 runs sub-agents (Context Pruner, Nit Pick Nick) automatically, which can make even simple tasks expensive. Use --mode free via --budget flag for cost-sensitive work.

TUI Stats View

Press s in the TUI to toggle the stats/charts view, which shows:

• Cost by Agent — horizontal bar chart of spend per agent
• Success Rate — bar chart of done/merged percentage per agent
• Budget Usage — gauge bars for configured budget windows
• Summary — task counts, total/today cost, token totals, and a cost sparkline

Press a to toggle between today-only and all-time task views.

Skills

Skills are methodology files loaded from ~/.aid/skills/ and appended to the effective prompt under a --- Methodology --- section. They make agent behavior more consistent across runs.

Skills are auto-injected by default: coding agents (codex, opencode, cursor, kilo, codebuff) get the implementer skill, and gemini gets the researcher skill. Use --skill to add extras or --no-skill to disable auto-injection.

Examples:

aid config skills

aid run codex "Refactor the retry code path" \
  --dir . \
  --skill code-scout \
  --skill test-writer \
  --verify auto

aid run opencode "Rename TaskRow to BoardRow" --dir . --no-skill

Teams

Teams provide knowledge context and soft agent preferences for different workflows. Each team has preferred agents (scoring boost in auto-selection), capability overrides, behavioral rules, and a knowledge directory.

# Create a team
aid team create dev

# Configure in ~/.aid/teams/dev.toml

[team]
id = "dev"
display_name = "Development Team"
preferred_agents = ["codex", "opencode", "cursor"]
default_agent = "codex"

# Always-injected constraints (no relevance filtering)
rules = [
    "Do NOT run cargo fmt or any auto-formatter",
    "Only git add files you explicitly modified",
]

# Override agent scoring for this team's tasks
[team.overrides.opencode]
simple_edit = 10
refactoring = 7

Team knowledge is stored in ~/.aid/teams/<id>/knowledge/ and auto-injected (relevance-filtered) when --team is used. Rules are always injected without filtering.

aid team list                              # list all teams
aid team show dev                          # show team config + knowledge + rules
aid run codex "implement feature" --team dev   # inject dev team context
aid batch tasks.toml --parallel            # batch with [defaults] team = "dev"

Project Profiles

Project-level configuration via .aid/project.toml sets defaults for all tasks dispatched within a repository. Built-in profiles expand into sensible presets:

# Initialize in current repo
aid project init
# → creates .aid/project.toml + .aid/knowledge/KNOWLEDGE.md

aid project show

[project]
id = "my-app"
profile = "production"    # hobby | standard | production
team = "dev"
language = "rust"
rules = [
    "File size limit: 300 lines per file",
]

Profile	Verify	Budget	Rules
hobby	-	$5/day, prefer_budget	-
standard	auto	$20/day	All new functions must have tests
production	cargo test / npm test	$50/day	Tests required, no unwrap(), cross-review

Project defaults act as CLI fallbacks — explicit flags always win. Rules are always injected into agent prompts (no relevance filtering). Knowledge in .aid/knowledge/ is relevance-filtered like team knowledge.

Agent Store

aid includes a GitHub-backed community agent store for discovering and installing custom agent definitions.

# Browse all available agents
aid store browse

# Search for specific agents
aid store browse coding

# Preview an agent's configuration
aid store show community/aider

# Install an agent (with optional version pinning)
aid store install community/aider
aid store install community/aider@1.2.0

# Check for updates
aid store update
aid store update --apply

Packages can bundle agent configs, skills, and hooks together. Installing a package installs all components and records versions in ~/.aid/store.lock.

Installed agents appear in aid config agents and participate in auto-selection via their capability scores. The store is backed by agent-tools-org/aid-agents — community contributions welcome.

Task Lifecycle Hooks

Define shell hooks that run at key points in the task lifecycle. Hooks receive task JSON on stdin.

Configure hooks in ~/.aid/hooks.toml:

[[hook]]
event = "before_run"
command = "~/.aid/hooks/validate.sh"

[[hook]]
event = "after_complete"
command = "~/.aid/hooks/notify.sh"
agent = "codex"

[[hook]]
event = "on_fail"
command = "~/.aid/hooks/alert.sh"

Or pass hooks per-task via CLI:

aid run codex "Implement feature" --hook before_run:./validate.sh --hook on_fail:./alert.sh

Batch files support hooks in [defaults] and per-task:

[defaults]
hooks = ["before_run:./validate.sh"]

[[task]]
agent = "codex"
prompt = "Implement feature"
hooks = ["after_complete:./notify.sh"]

Hook events:

• before_run — runs after task creation, before agent starts. Fails the task if hook exits non-zero.
• after_complete — runs after task completes (after verify). Best-effort.
• on_fail — runs when task fails. Best-effort.

Prompt Budget

Check skill token overhead with aid config prompt-budget:

$ aid config prompt-budget
Skill Token Budget:
  code-scout     ~195 tokens
  debugger       ~219 tokens
  implementer    ~323 tokens
  researcher     ~209 tokens
  test-writer    ~199 tokens
  ─────────────────────
  Total:         ~1145 tokens

Token usage is also logged during dispatch:

[aid] Skills loaded: 1 skills, ~323 tokens
[aid] Context injected: 2 files, ~450 tokens

Milestones

aid injects milestone guidance into prompts so agents emit progress markers that the watcher can parse and surface in aid watch, aid board, and the TUI.

Expected milestone format:

[MILESTONE] mapped the failing code path
[MILESTONE] implemented the fix
[MILESTONE] verified tests and summarized the diff

Agent Memory (Blackboard)

aid includes a shared memory system that lets agents build up knowledge across tasks. Memories are stored in SQLite alongside tasks and automatically injected into agent prompts when relevant.

Memory types:

• Discovery — new findings about the codebase or environment
• Convention — patterns, naming rules, or style decisions
• Lesson — mistakes to avoid (auto-expires after 30 days)
• Fact — verified constants (addresses, versions, config values)

Agents can emit memories by including [MEMORY: type] content tags in their output. These are automatically extracted and deduplicated after task completion.

# Manual memory management
aid memory add discovery "The retry module uses exponential backoff capped at 45s"
aid memory add convention "All SQL migrations use ALTER TABLE with DEFAULT values"
aid memory list
aid memory list --type lesson
aid memory search "retry"
aid memory forget mem-a1b2

Memories are auto-injected into prompts during dispatch. Agents see a --- Relevant Memories --- section with matching memories from previous tasks.

Verify Status

Tasks now track verification outcome separately from execution status via verify_status:

• Skipped — no --verify was set
• Pending — verify hasn't run yet
• Passed — verify command succeeded
• Failed — verify command failed (task may still be marked Done)

The board displays [VFAIL] next to tasks that completed but failed verification, making it easy to distinguish "agent crashed" from "code doesn't pass checks".

Command Reference

Command	Purpose	Typical use
aid run	Dispatch one task to an agent. Supports --bg, --verify, --worktree, --on-done, --no-skill, --retry, --context, and --skill.	aid run codex "Implement retry logic" --dir . --worktree feat/retry --verify auto
aid batch	Dispatch a TOML batch file with DAG dependency scheduling. Auto-creates a workgroup and archives the file to ~/.aid/batches/.	aid batch tasks.toml --parallel --wait
aid watch	Follow live progress in text mode, quiet wait mode, or the TUI.	aid watch --tui, aid watch t-1234, aid watch --quiet --group wg-a3f1
aid board	List tracked tasks with filters. Auto-detects zombie tasks. Use --stream for scrollback-preserving output.	aid board --today, aid board --stream --group wg-a3f1
aid show	Inspect one task's summary, diff, output, raw log, or AI-generated explanation. Diffs show changes vs main branch.	aid show t-1234 --diff, aid show t-1234 --output, aid show t-1234 --explain
aid usage	Render task-history usage plus configured budget windows. Supports --agent, --period, and --json.	aid usage, aid usage --agent codex --period 7d --json
aid retry	Re-dispatch a failed task with explicit feedback.	aid retry t-1234 --feedback "Reproduce the failure before editing."
aid respond	Send interactive input to a running background task.	aid respond t-1234 "yes"
aid benchmark	Dispatch the same task to multiple agents and compare results.	aid benchmark "Fix the bug" --agents codex,opencode --dir .
aid output	Show task output directly.	aid output t-1234
aid ask	Run a quick research or exploration task, optionally with file context.	aid ask "What changed in src/main.rs?" --files src/main.rs
aid mcp	Start the stdio MCP server so another tool can call aid natively.	aid mcp
aid merge	Mark done task(s) as merged. Supports --group for bulk merge, --approve for interactive approval via hiboss.	aid merge t-1234, aid merge --group wg-a3f1 --approve
aid clean	Remove old tasks/events and orphaned worktrees/logs. Supports --dry-run.	aid clean --older-than 7 --worktrees
aid config	Inspect agent profiles, skills, pricing (with --update to fetch latest), and prompt token budget.	aid config agents, aid config pricing --update
aid worktree	Explicit worktree lifecycle management: create, list, remove.	aid worktree create feat/x, aid worktree list, aid worktree remove feat/x
aid group	Workgroup management: create, list, show, update, delete, summary, finding, broadcast.	aid group create dispatch -c "Shared rollout notes", aid group summary wg-a3f1
aid store	Browse, install (with version pinning), update community agent/skill packages.	aid store install community/aider@1.0.0, aid store update --apply
aid upgrade	Upgrade aid to latest crates.io version (checks for running tasks).	aid upgrade, aid upgrade --force
aid agent	Manage custom agent definitions: list, show, add, remove, fork.	aid agent list, aid agent fork codex --as codex-fast
aid export	Export a task with full context (prompt, events, output, diff). Supports markdown and JSON.	aid export t-1234, aid export t-1234 --format json --output task.json
aid memory	Manage shared agent memory: add, list, search, update, forget.	aid memory add discovery "Finding", aid memory search "query"
aid tree	Show retry chain as an ASCII tree with agent/status/cost per node.	aid tree t-1234
aid query	Fast LLM query via OpenRouter (no agent startup). Free and auto tiers.	aid query "question", aid query --auto "question"
aid setup	Interactive setup wizard. Detects agents, sets API keys, initializes skills and templates.	aid setup
aid team	Manage teams: create, list, show, delete. Teams inject knowledge and rules into agent prompts.	aid team list, aid team show dev, aid team create ops
aid project	Initialize and show project configuration (.aid/project.toml). Profiles expand into verify/budget/rules defaults.	aid project init, aid project show
aid stop	Stop a running task. Graceful by default (SIGTERM + 5s + SIGKILL), --force for immediate SIGKILL.	aid stop t-1234, aid stop t-1234 --force
aid steer	Inject guidance into a running PTY task.	aid steer t-1234 "focus on tests"

Best Practices / Methodology

The Orchestrator Pattern

The most effective aid workflow is:

1. Plan the work — decompose into 5–10 independent subtasks.
2. Dispatch agents in parallel via batch files.
3. Monitor with background watch (auto-notifies on completion).
4. Review artifacts with aid show --diff.
5. Iterate with retries, or re-dispatch with --best-of for critical tasks.

Think big — 6–10 parallel agents finish faster and often produce better results than one agent doing everything serially. Each agent stays focused on a small, well-defined task.

A practical sequence looks like this:

# Phase 1: Research (free)
aid run gemini "Analyze src/api/ architecture, list public types and extension points" \
  -o /tmp/research.md

# Phase 2: Parallel implementation (batch file, 4–6 tasks)
aid batch feature-tasks.toml --parallel

# Phase 3: Background watch (push notification, no polling)
aid watch --quiet --group wg-a3f1   # Bash run_in_background: true

# Phase 4: Review and iterate
aid show t-1234 --diff
aid retry t-1234 --feedback "Missing error handling in the timeout path"

For AI orchestrators (Claude Code, etc.): Use aid watch --quiet --group <wg-id> as a background command to get automatic completion callbacks instead of polling aid board.

Quality Tiers

Match effort to task importance:

Tier	When	Pattern
Draft	Exploration, prototyping	aid run codex "..." --dir .
Standard	Normal development	aid run codex "..." --worktree feat/x --verify auto
Reviewed	Important features	aid run codex "..." --verify auto --peer-review gemini
Best-of	Critical code paths	aid run codex "..." --best-of 3 --metric "<cmd>" --verify auto

--best-of N dispatches the same task to N agents (or the same agent N times), runs an optional --metric command on each result, and keeps the best. Use it for bug fixes, core modules, and public APIs where quality matters more than speed.

--peer-review <agent> sends the completed diff to a second agent for scored critique (1–10). Cheap agents like gemini make excellent reviewers.

Agent Selection Guide

auto uses a capability matrix to match agents to task types. The scores below reflect relative strengths (higher = better fit):

Agent	Research	Simple Edit	Complex Impl	Frontend	Debugging	Testing	Refactoring	Documentation
gemini	9	2	3	2	5	3	3	6
codex	1	4	9	4	7	7	8	3
opencode	1	8	3	2	4	4	4	5
kilo	1	7	2	2	3	3	3	4
cursor	2	4	7	9	5	5	6	4
codebuff	2	5	8	7	6	6	7	4

Additional scoring adjustments: budget mode boosts cheap agents (+4) and penalizes expensive ones (-6); high-complexity tasks boost codex/cursor (+2); rate-limited agents get -10; historical success rates apply ±2-3.

Scores above are per-agent baselines. When auto selects, it also factors in model capability (1-10 scale): Premium (cap 9-10): gpt-5.4, gemini-pro, cursor opus-thinking. Standard (cap 6-8): gpt-4.1, gemini-flash, cursor-auto, opencode/glm-5. Budget (cap 3-5): gpt-4.1-nano, gemini-flash-lite, mimo-free. Final score = (agent_base × 0.4) + (model_capability × 0.6). Use aid config agents to see all model scores.

If you are unsure, start with aid ask or aid run auto, then escalate to a more expensive agent only when the task scope is clear.

Use Skills To Enforce Quality

Skills give you repeatable task methodology instead of relying on ad hoc prompt wording. In practice: use code-scout for unfamiliar code, researcher for fact-heavy work, implementer for minimal diffs, test-writer for regression coverage, and debugger when the task starts with a failure.

Example:

aid run codex "Fix the MCP framing bug and add regression coverage" \
  --dir . \
  --skill code-scout \
  --skill debugger \
  --skill implementer \
  --skill test-writer \
  --verify auto

Workgroup-Based Batch Collaboration

A workgroup lets several agents collaborate without repeating shared context. Batch files support DAG dependencies via depends_on — tasks dispatch as soon as their dependencies complete.

Think in phases: research (free) → parallel implementation (4–6 agents) → integration + validation. Each agent gets a focused, bounded task.

[defaults]
agent = "codex"
dir = "."
verify = "cargo check"

# Phase 1: Research (free, fast)
[[task]]
name = "research"
agent = "gemini"
prompt = "Analyze src/api/ and src/types.rs. List all public types, relationships, and extension points for adding a webhook system."
output = "/tmp/research.md"
read_only = true

# Phase 2: Parallel implementation (all depend on research)
[[task]]
name = "types"
prompt = "Create src/webhook/types.rs with WebhookConfig, WebhookEvent, WebhookPayload structs. Use serde. Match patterns in src/types.rs. Include tests. Keep < 150 lines."
worktree = "feat/webhook-types"
depends_on = ["research"]

[[task]]
name = "handler"
prompt = "Create src/webhook/handler.rs that sends HTTP POST on task completion. Use reqwest with 10s timeout. Log + continue on error. Include tests. Keep < 200 lines."
worktree = "feat/webhook-handler"
depends_on = ["research"]

[[task]]
name = "config"
prompt = "Add [[webhook]] config parsing to src/config.rs with url, events, headers fields. Include tests for valid/invalid configs. Keep changes < 100 lines."
worktree = "feat/webhook-config"
depends_on = ["research"]

[[task]]
name = "cli"
prompt = "Add 'aid webhook test <url>' command in src/cli.rs and src/cmd/webhook.rs. Send test payload, print result. Keep < 80 lines."
worktree = "feat/webhook-cli"
depends_on = ["research"]

# Phase 3: Integration (depends on all implementations)
[[task]]
name = "integration"
prompt = "Wire webhook handler into task completion flow in src/watcher.rs. Import from src/webhook/. Call on Done/Failed. Add integration test. Keep < 50 lines."
worktree = "feat/webhook-integration"
depends_on = ["types", "handler", "config"]
verify = "cargo test"

# Phase 4: Docs (cheap agent, depends on CLI)
[[task]]
name = "docs"
agent = "opencode"
prompt = "Add webhook configuration section to README.md. Show config.toml example and 'aid webhook test' usage. Keep < 40 lines."
worktree = "feat/webhook-docs"
depends_on = ["cli"]

Dispatch and monitor:

aid batch webhook.toml --parallel
aid watch --quiet --group <wg-id>   # background, auto-notifies on completion

Batch dispatches with 2+ tasks auto-create a workgroup. The batch file is archived to ~/.aid/batches/.

For critical tasks within a batch, use best_of = 3 to dispatch to multiple agents and keep the best result:

[[task]]
name = "critical-fix"
agent = "codex"
prompt = "Fix the race condition in src/store.rs. Add a test that reproduces it."
worktree = "fix/store-race"
best_of = 3
metric = "cargo test 2>&1 | grep -c 'test.*ok'"
verify = "cargo test"

Cost Optimization Tips

• Use aid ask or gemini first when the task is still exploratory.
• Prefer opencode for straightforward single-file edits or rename work.
• Use auto when you want a reasonable default without thinking about the agent first.
• Set [[usage.budget]] entries and check aid usage before long coding sessions.
• Reuse workgroups so shared context is stored once instead of repeated in every prompt.
• Use --model only when you need a specific backend behavior or cost profile.
• Use --on-done "command" to get notified when a background task completes (sets AID_TASK_ID and AID_TASK_STATUS env vars).
• Use --template <name> to wrap prompts with structured methodology (bug-fix, feature, refactor).
• Use --repo /path/to/other-project to dispatch tasks to a different git repository.
• Use --budget to force cheaper agent/model selection for low-priority tasks.
• Low-value tasks (tests, formatting, linting, docs) auto-detect as budget mode.
• Use read_only = true in batch tasks for research/review that should not modify files.
• Use aid benchmark to compare agent quality/speed/cost on the same task.
• Use codebuff with --budget for cost-sensitive tasks — the SDK's sub-agents can make simple tasks expensive in normal mode.
• Configure webhooks in config.toml for Slack/Discord notifications on task completion.

Built-in Skills

The default skill directory is ~/.aid/skills/.

Skill	Description
test-writer	Writes tests that target real failure modes, boundary cases, and integration seams instead of mirroring the implementation.
code-scout	Maps the entry point, call chain, relevant files, patterns, and risks before a change is made.
researcher	Collects verified information from primary sources, records confidence, and extracts facts that are safe to use downstream.
implementer	Makes the requested change with a minimal diff, matches the local style, and verifies the result.
debugger	Reproduces issues, traces execution, isolates the root cause, and validates the fix with evidence.

MCP Integration

aid can run as a stdio MCP server so Claude Code or another MCP client can call it without shell parsing.

Start the server directly:

aid mcp

The server exposes these tools:

• aid_run
• aid_board
• aid_show
• aid_retry
• aid_usage
• aid_ask

To connect from Claude Code, register aid as a stdio MCP server in your Claude Code MCP configuration. The exact config file location depends on your Claude Code setup, but the server definition itself looks like this:

{
  "mcpServers": {
    "aid": {
      "command": "aid",
      "args": ["mcp"]
    }
  }
}

If you are developing from source instead of using an installed binary, point Claude Code at cargo run:

{
  "mcpServers": {
    "aid-dev": {
      "command": "cargo",
      "args": [
        "run",
        "--manifest-path",
        "/absolute/path/to/aid/Cargo.toml",
        "--",
        "mcp"
      ]
    }
  }
}

Once connected, Claude Code can call aid_board to list tasks, aid_show to inspect artifacts, aid_run to dispatch new work, and aid_retry to iterate on failures.

Configuration

By default, aid stores state in ~/.aid/. Override it with AID_HOME when you want a disposable sandbox or separate environment.

Example:

export AID_HOME=/tmp/aid-dev

Typical directory layout:

~/.aid/
├── aid.db
├── config.toml
├── logs/
│   ├── t-1234.jsonl
│   └── t-1234.stderr
├── jobs/
│   └── t-1234.json
├── batches/
│   └── 20260313-112850-v15-fixes.toml
├── hooks.toml
├── skills/
│   ├── code-scout.md
│   ├── debugger.md
│   ├── implementer.md
│   ├── researcher.md
│   └── test-writer.md
├── agents/
│   └── *.toml
└── cargo-target/

What lives there:

• aid.db: SQLite task, workgroup, event, and memory store
• logs/: raw agent output plus stderr capture
• jobs/: detached background worker specs
• batches/: archived batch TOML files (auto-saved after dispatch)
• hooks.toml: task lifecycle hooks (before_run, after_complete, on_fail)
• skills/: methodology files loaded by --skill (auto-injected by default)
• templates/: prompt templates loaded by --template (see default-templates/ for examples)
• agents/: custom agent TOML definitions
• cargo-target/: shared Rust build cache for worktree-based tasks

Configure budgets and webhooks in ~/.aid/config.toml:

[[usage.budget]]
name = "codex-dev"
agent = "codex"
window = "24h"
task_limit = 20
token_limit = 1000000
cost_limit_usd = 15.0

[[usage.budget]]
name = "claude-code"
plan = "max"
window = "5h"
request_limit = 200
external_requests = 120
resets_at = "2026-03-13T02:00:00+07:00"
notes = "Track Claude Code separately from aid task history."

Then inspect usage and budget status:

aid usage

aid usage combines tracked task history with any external counters you record in config.toml.

Webhooks

Configure webhooks to receive notifications when tasks complete:

[[webhook]]
name = "slack-notify"
url = "https://hooks.slack.com/services/..."
on_done = true
on_failed = true

Webhooks fire automatically when background tasks reach a terminal state. Custom headers can be added via headers.

Reliability

aid includes several mechanisms to keep long-running multi-agent workflows healthy:

• Zombie detection: aid board automatically detects dead worker processes (including defunct/zombie state) and marks their tasks as FAILED.
• Max task duration: Tasks running longer than 60 minutes are automatically killed and marked FAILED.
• Auto-commit enforcement: Background worktree tasks auto-commit uncommitted changes after completion, preventing lost work.
• Zombie recovery: When a zombie task is detected in a worktree with uncommitted changes, those changes are preserved via auto-commit before marking the task as failed.
• Shared build cache: Rust worktree tasks share CARGO_TARGET_DIR to avoid redundant recompilation across parallel dispatches.
• Worktree escape detection: After each worktree task, aid checks if the agent accidentally modified the main repo and warns with a file list.
• Auto merge on aid merge: Merges the worktree branch into the current branch, runs pre-merge verification, and cleans up the worktree directory.
• SQLite concurrency: busy_timeout=5000 prevents "database is locked" errors under parallel task access.
• Fallback chain: When an agent is rate-limited, aid suggests the next capable alternative (codex → cursor → opencode → kilo).
• Retry worktree preservation: When a failed task's worktree is auto-cleaned, retries recreate a fresh worktree on the same branch instead of falling back to the main repo.

Architecture

At a high level, aid is a CLI front end over a task manager, a watcher pipeline, persistent storage, and agent-specific adapters.

The diagram below is adapted from DESIGN.md to reflect the current show command name:

┌─────────────────────────────────────┐
│           aid (CLI binary)          │
├──────┬──────┬──────┬───────┬────────┬───────────┤
│ run  │ watch│ show │ board │ usage  │ benchmark │  ← user-facing commands
├──────┴──────┴──────┴───────┴────────┤
│           Task Manager              │
│  ┌────────┐ ┌────────┐ ┌────────┐  │
│  │Classif.│ │ Watch  │ │ Store  │  │
│  │+ Agent │ │ Engine │ │(SQLite)│  │
│  │Registry│ │        │ │        │  │
│  └────┬───┘ └────┬───┘ └────┬───┘  │
│       │          │          │       │
├───────┴──────────┴──────────┴───────┤
│         Agent Adapters              │
│  ┌──────┐ ┌─────┐ ┌────────┐ ┌──────┐ ┌────┐ ┌───┐ ┌────────┐ ┌──────┐
│  │Gemini│ │Codex│ │OpenCode│ │Cursor│ │Kilo│ │Codebuff│ │Custom│
│  └──────┘ └─────┘ └────────┘ └──────┘ └────┘ └───┘ └────────┘ └──────┘
└─────────────────────────────────────┘

How the pieces fit together:

• The CLI entrypoint parses commands and routes them to task-oriented handlers such as run, watch, show, usage, and mcp.
• The task classifier categorizes prompts into eight task types and estimates complexity, then the capability matrix scores each agent to pick the best fit.
• The agent registry selects and instantiates adapters for gemini, codex, opencode, cursor, kilo, and codebuff.
• The watcher parses streamed or buffered output into milestones, tool activity, usage totals, and completion events.
• SQLite keeps task history, workgroups, and events queryable for board, show, watch, usage, and MCP clients.
• Artifact files under ~/.aid/ preserve the raw execution trail so the dispatcher can review what actually happened.

That combination is the core value of aid: one binary that turns a pile of incompatible AI CLIs into a trackable, reviewable, and methodology-aware team workflow.