AIOS

Your coding agents can write code. AIOS makes them earn the merge.

Two independent agents. Isolated worktrees. Tests before approval.
A complete evidence trail after every run.

Website · Quick start · Why AIOS · How it works · Architecture · Releases

---

AIOS is a local-first command-line orchestrator for Claude Code and OpenAI Codex. Give it a requirement and it turns that prompt into a reviewed specification, a dependency-aware task plan, isolated code changes, verification results, and a merge-ready pull request.

The core rule is enforced in code: the agent that writes a change is never the agent that reviews it.

$ aios ship "Add a health endpoint with tests and update the API docs"

  prompt
    → dual-agent spec
    → task DAG
    → isolated worktrees
    → coder ↔ independent reviewer
    → test / lint / typecheck / build
    → rebase + re-review + re-verify
    → pull request + CI
    → squash merge

Why AIOS

Most coding-agent workflows optimize for producing a diff. AIOS optimizes for producing a diff you can trust.

One-agent loop	AIOS
The author reviews its own work	A different engine must review every change
Edits happen in your checkout	Every task runs in its own Git worktree
Tests are an optional follow-up	Red verification is a merge blocker
Parallel work shares mutable state	Task branches and worktrees are physically isolated
A rebase can invalidate approval	Rebased code is reviewed and verified again
Failures disappear into chat history	Prompts, raw responses, checks, and verdicts stay on disk
Stuck loops burn budget indefinitely	Bounded escalation ends in a structured human handoff

AIOS is not another chat interface. It is the control plane around the agents you already use.

Quick start

1. Install

You need Git 2.40+ and authenticated claude and codex CLIs. The full ship flow also uses an authenticated GitHub CLI (gh).

npm install -g @anthropic-ai/claude-code @openai/codex
npm install -g @devin-lai/aios

You can also download a native binary from the latest GitHub release, or install from source:

go install github.com/devin-lai/AIOS/cmd/aios@latest

2. Initialize a repository

cd your-repo
aios init
aios doctor

aios init detects Go, Node.js, Python, and Rust verification commands. aios doctor checks Git, both agent CLIs, authentication, configuration, and the GitHub CLI before you spend a run.

3. Ship a change

aios ship "Add request IDs to every API response, including tests and docs"

On success, AIOS opens a pull request from aios/staging, waits for CI, and squash-merges it. Your working checkout is not switched, rebased, or dirtied during task execution or merge-queue integration.

Want a checkpoint before execution? Start the interactive planner, refine the specification, then ship it from the same session:

aios
# describe the change, inspect it with /show, then run /ship

How it works

flowchart LR
    P["One prompt"] --> S["Dual-agent spec"]
    S --> D["Dependency-aware task DAG"]
    D --> A["Task A<br/>isolated worktree"]
    D --> B["Task B<br/>isolated worktree"]
    A --> VA["Test · lint · typecheck · build"]
    B --> VB["Test · lint · typecheck · build"]
    VA --> RA["Independent reviewer"]
    VB --> RB["Independent reviewer"]
    RA -- "revise" --> A
    RB -- "revise" --> B
    RA -- "approve" --> Q["Merge queue"]
    RB -- "approve" --> Q
    Q --> G["Rebase · re-verify · re-review"]
    G --> PR["Pull request + CI"]
    PR --> M["Squash merge"]

Loading

The guardrails are the product

• Independent review is mandatory. Configuration rejects identical coder and reviewer engines, and runtime selection checks the invariant again.
• Every task gets a clean room. Dedicated branches and Git worktrees keep parallel changes away from each other and away from your checkout.
• Approval is not enough. Tests, lint, type checks, and builds feed directly into the review verdict. A red gate cannot merge.
• Rebases invalidate old evidence. The merge queue syncs the rebased task worktree, then runs both review and verification again.
• The audit trail survives failure. Partial rounds, retry attempts, prompts, raw responses, MCP calls, and verification output are written atomically.
• Cancellation is a real state transition. Ctrl-C reaches workers, child processes, verification, and Git recovery without marking unfinished work as successful.

Choose your workflow

Command	Best for
aios	Interactive spec refinement, then /ship
aios "<prompt>"	Generate .aios/project.md without executing it
aios -p "<prompt>"	Print a polished spec with no file write
aios ship "<prompt>"	One prompt to reviewed, verified, merged pull request
aios exec "<prompt>" --json	Headless automation with JSONL events
aios run	Execute pending task files in dependency order
aios duel "<task>"	Let both engines implement the same task and select a winner
aios review <pr>	Run a conservative cross-model review of an existing PR
aios serve	Turn aios:do GitHub issues into shipped changes
aios status / cost / lessons	Inspect progress, spend, and recurring review findings

Run aios <command> --help for the complete flag reference.

Interactive planning

Run aios with no arguments to refine a specification before implementation:

$ aios
❯ Build a CLI that syncs notebooks across machines

  ✓ draft-claude
  ✓ draft-codex
  ✓ merge
  ✓ polish

Spec updated. /show to inspect, /ship to implement, or keep refining.
❯ Tighten the conflict-resolution and offline requirements
❯ /ship

Every intermediate spec stage is saved under .aios/runs/<run-id>/specgen/. Resume a previous planning session with aios resume --last or aios resume <session-id>.

Duel and pull-request review

Race both engines on the same task without committing either result:

aios duel "Add a rate limiter to /login with unit tests"
aios duel "Add a rate limiter to /login with unit tests" --apply

Or review an existing pull request with both engines and synthesize the more conservative verdict:

aios review 42
aios review https://github.com/owner/repo/pull/42 --post

Issue-bot mode

aios serve watches for issues labeled aios:do, ships each one, comments with the pull request, and reports structured failures back to GitHub.

gh auth login
aios serve --repo devin-lai/AIOS
aios serve --repo devin-lai/AIOS --once

The daemon reconciles claimed issues after a restart. Current releases process one issue at a time.

Failure is a first-class outcome

AIOS does not hide hard tasks behind an endless spinner. A stalled change moves through a bounded recovery ladder:

1. Retry transient engine failures with exponential backoff.
2. Feed verification failures and reviewer issues into a revision round.
3. Escalate with the unresolved constraints made explicit.
4. Decompose an oversized task into a smaller dependency-aware subgraph.
5. Regenerate the specification when sibling failures point to a spec-level problem.
6. Stop with [NEEDS HUMAN], stable reason codes, and the full evidence trail.

Typical structured output:

003-migrate-schema: [NEEDS HUMAN] stall_no_progress
  unmet: backwards compatibility, rollback coverage
  blocking: schema.sql adds a NOT NULL column without a default

007-refactor-auth: upstream_blocked
  root cause: 003-migrate-schema

Unfinished work stays on its task branch for inspection or resume.

Inspect everything

Every run produces a local record designed for debugging, cost inspection, and review—not a lossy chat transcript.

.aios/runs/<run-id>/
├── specgen/
│   ├── 1-draft-claude.md
│   ├── 2-draft-codex.md
│   ├── 3-merge.md
│   ├── 4-polish.md
│   └── 5-critique.md
└── <task-id>/
    ├── round-1/
    │   ├── coder.prompt.txt
    │   ├── coder.response.raw
    │   ├── coder.attempts.json      # present when retries occur
    │   ├── verify.json
    │   ├── reviewer.prompt.txt
    │   ├── reviewer.response.raw
    │   ├── reviewer-response.json
    │   └── mcp-calls.json
    └── report.md

Use the built-in inspection commands:

aios status
aios cost --all
aios lessons

Secure by default

• Agent authentication remains owned by the installed CLIs; AIOS invokes them as child processes.
• MCP access is deny-by-default and scoped per task with mcp_allow.
• Resolved MCP secrets are kept out of the permanent audit directory; the retained configuration is redacted.
• Task IDs are validated before they can become file paths or branch names.
• State and audit writes use temp file + fsync + rename semantics.

AIOS currently provides Git worktree isolation, not container isolation. Treat configured tools and MCP servers as trusted local executables.

Configuration

aios init writes .aios/config.toml. The settings most teams tune are:

schema_version = 1

[project]
base_branch = "main"
staging_branch = "aios/staging"

[engines]
coder_default = "claude"
reviewer_default = "codex" # must differ from coder_default

[budget]
max_rounds_per_task = 5
max_tokens_per_task = 200000
max_wall_minutes_per_task = 30
stall_threshold = 3

[parallel]
max_parallel_tasks = 4

[verify]
test_cmd = "go test ./..."
lint_cmd = "go vet ./..."
typecheck_cmd = ""
build_cmd = "go build ./..."

MCP tools

Scaffold a server, then allow it only on the tasks that need it:

aios mcp list
aios mcp scaffold github
aios mcp scaffold fs-readonly
aios mcp scaffold playwright

---
id: 003-add-login
kind: feature
mcp_allow: [github]
acceptance:
  - login attempts are rate limited
---

Every MCP call is recorded with its task and round.

Project status

AIOS is pre-1.0. The closed-loop pipeline is covered by unit, integration, race-detector, and opt-in real-engine end-to-end tests. Interfaces and defaults may still evolve between minor releases.

Current limitations:

• Worktrees isolate Git state; they are not a security sandbox.
• aios serve processes issues sequentially.
• Quality claims are structural; the project does not yet publish a comparative empirical evaluation suite.

See the changelog, architecture guide, and end-to-end test guide for the details behind those claims.

Contributing

Bug reports, focused feature proposals, tests, and documentation improvements are welcome. Start with CONTRIBUTING.md, then open an issue or pull request.

License

MIT © AIOS contributors.