aid
Color theme

AI dispatch / v11.1.0

aid

Spend other contexts.
Keep your attention for decisions.

Dispatch execution into separate agent sessions and worktrees. Bring back conclusions, with the full evidence available when you need it.

Your context is finite. Your judgment stays yours.

curl -fsSL https://aid.agent-tools.org/install.sh | sh
Start your first task

An explainer with burned-in English captions about separate task contexts, provider routing, verification, independent audits and preserved work.

AI work, under your control.
About the numbers

14,998 tasks on one developer machine, 2026-03-15–2026-10-14. 27 agent CLIs and 104 named models.

Median task: 2,318,097 tokens. Median session: 11 tasks; 34,306,076 tokens of work; 422,762 dispatcher peak context tokens; 84.7× median ratio.

703 audits with explicit verdicts: 352 SHIP, 313 FIX, 38 BLOCK. 351 sent the work back.

Token counts are reported by each agent CLI and include cache reads.

Verdicts count only reports with an explicit 'Verdict: SHIP|FIX|BLOCK' line.

Dispatcher sessions are those whose Claude Code transcript was still on disk.

Difficulty and rigor are declared by the caller; aid does not pick the model.

Premium route: aid's estimated price above $1.50 per million tokens; estimates come from model pricing, not bills, and tasks on unpriced routes are excluded.

Case source: a fix in aid's repository, 2026-10-14: Shell semantics for --verify. 35,284,164 tokens of work and 42,052 report bytes read by the dispatcher.

01 / Context is the budget

Execution elsewhere.
Judgment here.

A person has finite attention. A main agent session has a finite context window. Keep the heavy work with the task; bring back what the next decision needs.

  1. Delegate execution

    Give code tasks their own agent sessions and isolated worktrees. Read-only audits inspect the chosen checkout from separate report tasks.

  2. Bring back conclusions

    Read a saved report, summary line, typed answer, verdict, or diff. The full transcript stays with the task, available on demand.

  3. Keep the judgment

    Verify by running the checks. Outcome is not status. Acceptance is explicit; merge and artifact collection are separate steps.

Other contexts do the work Your session stays on a quiet rail. A code task leaves into its own context and worktree, runs and verifies there, then returns a report for your decision. Other task branches represent separate contexts; the full transcript stays with each task. your session own context code task / worktree execute verify saved report you decide
Execution lives in task contexts. A small report returns; the transcript stays on demand.
Task lifecycle A task branches from main into an isolated worktree. Verify and show support review before explicit acceptance and merge rejoin main. main 01 Advise 02 Run branch / worktree 03 Verify 04 Show 05 Accept explicit decision / merge
Advise → isolated branch → verify → review → explicit acceptance and merge.

The caller's brief and retry feedback are never compressed. Auxiliary context is bounded, with omission notes; large briefs can still exceed an agent's window.

02 / Independent cross-audit

One change.
Independent reports.

Audit the same change through different providers. Each read-only report task gets its own agent session and saves its own report; the repository under test must stay unchanged.

A route is <cli>/<provider>/<model>. One exhausted route says nothing about another provider. Choose a different provider, never a weaker model on the caller's pool.

Independent providers, visible disagreement One fixed change is audited in parallel by three read-only report tasks on different providers. Separate reports return SHIP, FIX and SHIP in this illustration. The differing FIX remains visible at the you decide station; no majority vote accepts the change. your session A B C providers distinct routes read-only report tasks SHIP FIX SHIP you decide
Separate providers return separate reports. Disagreement stays visible; you decide.

Pull out SHIP / FIX / BLOCK without reading every report into your context. Keep disagreement visible, inspect the cited evidence, and decide yourself.

From a terminal outside an aid task, use installed CLIs configured for distinct providers. Replace /path/to/change with the checkout to audit and keep its HEAD fixed during review.

audit="Read-only cross-audit of HEAD. Report SHIP/FIX/BLOCK with evidence. Do not modify files."
aid run codex "$audit" --read-only --dir /path/to/change --bg \
  --difficulty moderate --budget standard --urgency normal --rigor standard
aid run claude "$audit" --read-only --dir /path/to/change --bg \
  --difficulty moderate --budget standard --urgency normal --rigor standard
aid run gemini "$audit" --read-only --dir /path/to/change --bg \
  --difficulty moderate --budget standard --urgency normal --rigor standard

Optional verdict extraction: aid classify sends the report to an external API and requires a key in the macOS keychain. Its answers describe the report, not proof that the report is true. Read the classify guide before using it.

aid show t-audit-1 --output --full | aid classify \
  --choice verdict='What final verdict does this audit give?' --options SHIP,FIX,BLOCK \
  --noul evidence='Does the audit cite test output or command output as evidence?'

--audit schedules an additional post-task cross-audit and requires aic. --rigor critical requires verification and post-task audit, explicitly or by project defaults.

Run an independent cross-audit ↗

03 / Failure keeps its evidence

Keep the work.
Fix the cause.

Task worktrees and salvage commits preserve failed work. Shared checkouts use recovery refs. Rejection preserves artifacts; acceptance and integration are separate decisions.

Failure keeps its evidence A failed verification retains the task worktree and salvage commit. Retry with feedback creates a linked attempt using the kept work. Rejection keeps artifacts; acceptance is a separate explicit decision. main Run Verify fails Salvage commit worktree kept aid retry new attempt Reject keeps artifacts · Accept is separate
Failed work stays. Retry uses it with feedback; acceptance is separate.

04 / Capabilities

Coordinate the work.
Keep the judgment.

A

Routing

Advice from third-party leaderboards: Terminal-Bench, Epoch ECI, SWE-bench Verified, and LMArena. Observed quota informs routes; cascades can continue after failure.

Missing capability or quota evidence stays unknown. aid assigns no scores of its own.

Routing across provider branches A provider branch is on hold. The task takes an explicitly chosen different provider route; a weaker model on the same pool is not delegation. main provider A hold / quota provider B chosen route run result
A hold on one provider does not establish another provider’s availability. Choose the route explicitly.
B

Isolation & custody

Git worktrees, failure salvage, saved read-only audit reports, and container or sandbox execution. Work is preserved until acceptance and safe collection.

Sandbox support depends on the agent adapter.

C

Scale

Dependency-aware batch DAGs and workgroups keep tasks coordinated. Best-of runs, AI judges, and peer review provide additional comparisons and critique.

Dependency waves in separate worktrees Tasks A and B form an independent wave in distinct worktrees. Both depends_on edges must complete before C becomes ready; D follows C. One moving token traces the dependency waves. main A B worktrees A / B depends_on A + B C ready D follows C wave complete
Independent tasks form a wave; depends_on edges unlock the next tasks in separate worktrees.
D

Build & verify

Route Cargo builds to rbox with remote-build support. Verification records its own result, including failed checks and inconclusive infrastructure or timeout states.

E

Interfaces

Work through the CLI, terminal UI, or stdio MCP server. The optional authenticated HTTP API and SSE server connects clients, including AID Command for macOS and iPadOS.

The HTTP server requires a build with the web feature.

05 / Supported agents

Different CLIs.
One task interface.

14 built-in adapters. Install and authenticate the agent CLIs separately.

gemini agy qwen codex copilot opencode commandcode kilo mimocode cursor droid oz claude grok

Custom agents extend the same interface. Explore the adapters ↗

06 / Security

Review before you trust.

AI agents have broad file system and shell access and can send data to providers. Use a dedicated development machine or VM, review output before merging, and preview with dry-run.

Read-only mode checks a Git snapshot after execution; for adapters without a native read-only mode, this is how changes are detected. It is not a process sandbox. The comparison covers the whole repository, its HEAD and current branch; ignored untracked files and paths outside the repository are outside it.

Read-only detection after the run A Git snapshot is taken before the agent runs. After exit the repository is compared, and a change is detected and reported. Read-only enforcement is a post-run check, not a sandbox. main snapshot agent runs writes can occur compare after exit change detected failure reported
Snapshot → run → compare after exit. Repository changes are detected and reported; this is not a sandbox.
Learn the review and custody flow ↗