What is AIDA?

#In short

What it is. A command-line tool (aida) plus an MCP server (aida mcp-serve) that sits inside a git repository. Requirements, decisions, comments, mail and lease records live in git on an orphan aida-store branch. Operational records such as review verdicts, merge holds, dispatch requests, handoff notes and standing orders live in local, git-ignored files under .aida/, and mandates live under ~/.aida/. AIDA controls how AI agents pick up work, review each other, and merge.

Who it is for.

• A developer who runs several AI coding agents (Claude Code, Codex CLI, Antigravity, or anything with a shell) on one codebase at the same time.
• Anyone who wants agents to work for hours without supervision while keeping control of what gets merged.
• Teams that need to answer, later, "why does this code exist, who approved it, and on what evidence?"

What it does, in plain terms:

• One shared source of truth. Requirements, decisions, bugs and design rulings are stored as versioned spec objects. Agents are told to read them before acting (through the project's instructions and skills), and // trace:<SPEC-ID> comments link code back to the spec that justified it.
• Separation of duties. AIDA refuses an approval recorded by a session it identifies as the change's author, and if it cannot establish who the author is, it refuses. The one exception is an opt-in, audited "solo human" mode, in which a human verified at a terminal may approve their own work. The review is recorded against written acceptance criteria. Changes to the gate code itself (aida-cli-lib/src/gate/) and to .aida/config.toml are on a protected list that a mandate cannot ship, so they need a human merge.
• Roles. An advisor plans and rules on designs, implementers build, reviewers check, and an integrator lands the work. Seat grants and gate checks enforce the key authorities: who may record a review, ship, clear a hold, or start a mandate.
• Delegated autonomy with limits. A human at a terminal can start a time-boxed mandate (8 hours by default, at most 24) that lets the advisor seat ship held PRs and queue dispatch work while the human is away. Work outside the mandate's scope waits for the human, and specs marked operator-only are never covered.
• A recorded trail. Review verdicts are recorded against exact commits. Mandate-driven actions, dispatch requests and their results, and spec status history are also recorded, so most "who decided this, on what evidence?" questions have a written answer.

Why it matters. The bottleneck in AI-assisted software is shifting from writing code to trust and coordination. AIDA is built so that a team, from a single developer up to a larger group, can supervise many agents working in parallel without losing control of quality or accountability. Multi-human use is still being hardened: today everything runs under one Unix user, and AIDA treats a same-user process that forges its files as outside its threat model, so separating one human from another is not yet a security boundary.

A governed software factory with selectable autonomy

Software factory describes the repeatable path from a specification to an implemented, tested, reviewed and merged change. Governed means that path has assigned responsibilities, recorded decisions, acceptance criteria and enforced authority limits. Selectable autonomy means the team chooses where human participation is required for each spec, rather than choosing one automation level for an entire project.

Four execution modes, plus a decision stop

These descriptive names explain the existing modes to a management audience; the CLI values in the second column remain the actual mode names. They are operating choices, not industry certification levels.

Decision pending (decide) sits outside this ladder. It blocks execution until the pending decision is resolved; no implementation harness runs. It is how AIDA represents work that is not ready to delegate, rather than asking an agent to invent an answer.

The execution mode is recorded on the spec. The advisor classifies the work, and aida do <SPEC> uses that classification to select the execution path. Moving toward more human involvement is permitted; reducing involvement requires an explicit --force override or a durable reclassification. A decide block cannot be bypassed with a mode override. See Work & autonomy for operational commands.

Where a dark factory fits

In the software use of dark factory, people define intent and validation while agents implement and validate changes without routine human coding or code review. StrongDM's software factory is one explicit example of that approach.

drain is AIDA's dark factory mode. For approved, authorized specs, agents implement, test, independently review and merge changes without routine human coding or code review. People define the intent, acceptance criteria and authority limits; the factory executes within them and escalates exceptions. AIDA lets a team run this mode alongside supervised, collaborative and human-led delivery, choosing the level of human involvement for each spec.

Selecting autonomy does not grant authority to bypass reviews, CI, merge holds or protected operations. Mandates and seat grants determine which actions are authorized and for how long; the execution mode determines how the work is carried out. A stopped gate or unresolved decision can still require a person. Here, delivery means reaching the merged code state; production deployment requires its own policy and automation.

For management, this supports a practical adoption path: start with supervised delivery, retain collaborative delivery for design-heavy work, and delegate well-specified work to autonomous delivery as its validation and operating evidence justify it. The goal is to choose the human attention each change needs and retain a record of what happened.

#How big is it, and why

Counts are for files tracked in git at origin/main 28bbe9d540b.

Why it is large:

• The scope is wide. A requirements store, git-backed sync, a merge train, a review gate, mandates and grants, sessions, mail, a scheduler, and four interfaces (command line, MCP, terminal UI and web server).
• The safety rules are written as tests. Ratchet tests fail the build if a forbidden code pattern comes back. They are verbose, but they are what keep the guarantees in the section above true.
• Comments carry explanations. Many record why a piece of code exists, with trace links to the spec, for the next agent to read.

There is some overlap. Approval decisions used to be made in more than one place. The ship gate and the review watcher's readiness report now share a single decision function (internal spec), so they cannot disagree. The size has a real cost, whatever the cause: every agent session spends context and build time navigating it. The work under way is to make the size cheaper to work in. The lib.rs split is done, the follow-on split of the crate into dependency-ordered crates is still open (internal spec), and a 28 October spike looked at carving out aida-core. The plan is to propose deleting code only where tools or usage data show it is unused.

What AIDA can measure and support for engineering management

AIDA reports on captured delivery evidence. People develop and review conversationally while configured agents maintain structured intent; reporting coverage depends on what those tools recorded. This capability map was checked on 29 October 2026. It does not present live project values or claimed savings. See the Metrics guide for sources and interpretation.

• Reported today: cycle-time activity percentiles and work/wait/unknown splits; commit-trailer attribution and spec/criteria evidence; recorded drain outcomes; effort/load and calibration reports; local command latency and error reports when telemetry is enabled. Unknown time and excluded items remain explicit. CLI invocation counts include agent activity and do not measure human productivity.
• Recorded with incomplete coverage: token usage from retained Claude Code/Codex artifacts with attributable session evidence, offline cost estimates for the pinned rate table's supported model/token classes, and local review findings/classification. The built-in ledger does not parse Antigravity artifacts. Unpriced or missing usage is not zero; cost estimates are not billing. The bundled rate table is versioned 2026-09-22.1 and prices only Claude Sonnet 4 (20250514) and Opus 4.1 (20250805), plus their listed aliases. Newer Claude models and Codex models remain unpriced.
• Derivable without a finished joined report: lines changed per spec and review rounds joined across change history require additional analysis, deduplication and coverage accounting. Existing cycle-time counters are not a complete verdict-history analysis.
• Not supported: measured hours saved against equivalent human work, proven ROI and reliable feature-duration forecasts. Recorded buckets and counts are proxies, not proof of business value.

Effort can be captured when work is opened, planned, shipped and reviewed. The capture model has open, plan, implementation/ship and review touchpoints; available records feed aida load report and aida load calibration. Calibration compares estimates/assessments with the implementer's declared ship bucket, not stopwatch measurements or equivalent human time. Buckets are 15m, 1h, 4h, 1d (8 work-hours) and 1w (40 work-hours). Missing touchpoints limit coverage; heft is a graph score, not an effort estimate.

Use aida metrics cycle-time, aida metrics agent-lift, aida metrics ai-lift, aida usage show, aida usage show --cost, aida review classes and command help to inspect the reports. Token provenance and local log coverage require interpretation; a project-wide total cannot be inferred from one attributed spec.

Air-gapped development.

• Works without a network: the requirements store, coordination, leases, mail, telemetry, the token ledger and the cost estimates are all local files or a git branch, and the MCP server talks over stdio. Any git server can act as the hub; this repo mirrors to a self-hosted GitLab. aida pr ship supports GitLab merge requests, but the merge train is GitHub only. Releases are prebuilt Linux tarballs (x86_64 and arm64), so installation can be offline, though aida upgrade needs a network.
• Network containment: for agent sessions launched in contained mode, an opt-in [contained] allowed_hosts setting restricts outbound network access.
• The coding agents are the limit: AIDA launches Claude Code, Codex CLI or Antigravity, and those CLIs need their model APIs. An air-gapped deployment therefore needs on-premises or local models that the vendor CLI itself can be pointed at. AIDA has no model layer of its own for coding agents. The only built-in local-model option is that the spec evaluator can call an OpenAI-compatible local endpoint (Ollama or vLLM, set with AIDA_LOCAL_LLM_ENDPOINT).

#Capabilities, and when to use each

Each row names the situation that should make you reach for the capability. The commands below exist in aida 0.16.0; run aida <command> --help for the details.

#What AIDA adds to GitHub, CI and Jira when the developers are AI agents

The real alternative to AIDA is not a pile of scripts. It is a team's standard tooling with AI agents plugged in: GitHub or GitLab with branch protection and required reviews, a merge queue, CI, an issue tracker such as Jira, and an agent such as Codex. That stack is mature, and AIDA builds on it rather than replacing it: AIDA ships through GitHub or GitLab and relies on their CI and required checks. The question is what that stack misses when the developers are agents. The common answer is that standard tooling assumes each developer is a separate, accountable human account. In this repository, all 36 PRs merged on 28 October were opened under one GitHub account (joemooney), whichever agent wrote them. GitHub therefore cannot tell the implementing agent from the reviewing agent. AIDA supplies that missing layer: agent identity and authority, coordination between concurrent agents, independent AI review in the loop, and traceability down to which agent acted on whose authority. The examples are from 28 October 2026.

#Why not just Codex skills plus a wrapper?

A fair question: why not write a few skills (instructions the agent loads) and a wrapper script instead?

When that is good enough. One human, one or two agents, low stakes, no parallel merges, and it's acceptable if the agent sometimes ignores a rule. In that setting, skills plus a wrapper are simpler and cheaper, and AIDA would be overkill.

The core difference. A skill is instructions to the model, so it works as advice. The model can misread it or skip it, and an agent can't reliably enforce rules on itself, especially one running in a sandbox that can't see the whole system. AIDA puts its key rules in code that runs outside the model's control:

• aida pr ship refuses a PR whose head is behind its base, and the review watcher holds back an automatic review of a behind head with overlapping paths, whatever the agent thinks.
• Verdicts are bound to an exact commit, and the merge is pinned to the approved head.
• Merge holds fail a required check until cleared. Clearing one by hand needs a human at a terminal, and a sensitive spec needs either that or a mandate the human started with --include-supervised.
• Mandates can only be started, renewed or stopped from an interactive terminal, outside an AIDA-launched agent session.
• Dispatch requests are validated when queued, and authority is re-checked at every checkpoint before a side effect. A replacement mandate does not revive requests that lapsed under an earlier one.
• Claims and leases are tied to live processes (PID plus start time). In the paths checked here, unreadable ownership or evidence makes the operation refuse.

What is already stable and isolated. These guarantees are not scattered through the codebase:

• The authority decisions (ship, merge, hold, verdict, seat, dispatch, mandate) live in one module, aida-cli-lib/src/gate/: 34 modules and about 24,000 non-test lines. That directory, plus the drift ratchet test that keeps the list complete, is on the mandate's protected list, so a mandate cannot ship changes to it.
• Ratchet tests keep that boundary and the other conventions from eroding. They catch new gate-like functions outside gate/, aliased imports into the dispatch code, raw git command builders beyond an allow-list, and growth of the legacy CLI Command enum.
• CLI commands are registered through a typed registry (command_registry::REGISTRY). A golden help snapshot test guards it, along with a test that every top-level name has exactly one owner.
• Skills, hooks and agent docs come from one template master (aida-core/templates/, with 59 skills), and make sync-templates and make check-templates keep the mirrors in line.

What sitting above the vendors buys you. The deeper question isn't size. It is whether a layer that sits above the vendor tools gives you security and options that being tied to one vendor's agent would not. In short, it means owning your data and keeping control of your own direction.

• You own the data. Specs, decisions, comments, mail, leases and the operation log live on the aida-store branch of your own git repository, so they move to any hub you choose. Review verdicts, merge holds, dispatch requests and results, handoff notes and standing orders are plain files in your checkout's .aida/ directory (git-ignored, so local to that clone), and mandates live in ~/.aida/. None of it is held in a vendor's cloud. Skills are authored once in a template master and shipped both as Claude skills and as a vendor-neutral pack (.agents/skills/) that Codex and Antigravity read. A unit test fails if a skill is neither shipped to that pack nor explicitly excluded.
• You aren't tied to one vendor. AIDA launches and drives Claude Code, Codex CLI and Antigravity, interactively (aida agent new claude|codex|antigravity) and headless (--vendor), behind the same roles, gates and records. You can mix vendors or switch between them, which helps when negotiating on price and protects you if a vendor changes its terms or features. The token ledger already reads both Claude Code and Codex logs.
• Enforcement doesn't rely on a vendor's model. The gates are AIDA code: ship and train checks, verdicts bound to a commit, merge holds, terminal-only mandates and dispatch re-checks. They behave the same whichever model wrote the change. They are not prompts that a different model might follow differently.
• You keep strategic options open. Because history and coordination aren't tied to a vendor, the whole record can move with you, and on-premises or air-gapped models remain an option later. Today the only built-in local-model hook is the spec evaluator's OpenAI-compatible endpoint (Ollama or vLLM). The coding agents still need whatever model API their vendor CLI uses.
• Today's limits, stated plainly. Vendor parity is uneven. Contained (sandboxed) sessions are supported only for Claude: the code applies containment to Claude alone, and refuses a contained launch on Codex or Antigravity with "the codex vendor cannot run a contained session" rather than quietly launching it uncontained. Much of the tooling and dogfood evidence is Claude-first. And the data lives in two places, the git store and local files, so moving the full history means copying .aida/ as well as the repository.

These protections aren't free to build. Concurrency control, crash-safe retries and identity that survives reused PIDs and inodes are where real bugs were found and fixed on 27–28 October: the inode-reuse identity collision (#3043), the dispatch occupancy scan misreading lease companion files (#3052), and writer build identity being compared by executable path instead of build (#3037).

To be fair to the other side. AIDA is large partly because it grew fast, and some of its approval logic has had overlapping paths (see "How big is it" above). Skills are still the right tool for guidance: how to plan, review or write a commit. AIDA ships its own skills for exactly that. So the real comparison is "skills plus an enforcement layer" against "skills alone".