# macOS / Linux
curl -sSfL https://raw.githubusercontent.com/autopus-ai/autopus-adk/main/install.sh | sh
Windows (CMD or PowerShell)
powershell -c "irm https://raw.githubusercontent.com/autopus-ai/autopus-adk/main/install.ps1 | iex"

Choose the workflow that fits the change

Start with one real task in an existing repository. After setup, run auto doctor in your terminal to check the installed platform wiring.

| Your task | Agent-chat entry point | Expected scope | | --- | --- | --- | | Reproduce and fix a bug within an existing contract | @auto fix "describe the failure" | Reproduction test, focused patch, verification; low-risk fixes do not need a full SPEC set | | Review existing changes | @auto review | Findings and verification evidence | | Build a feature with new requirements | @auto plan "describe the outcome", then @auto go SPEC-ID | Explicit acceptance criteria, implementation, applicable gates |

These examples use the Codex plugin router. Native Codex skills use $codex-auto-fix, $codex-auto-review, and the corresponding route names; Claude Code and OpenCode use /auto ....

Autopus is most useful when a team needs consistent delivery rules across coding tools and repositories. A single, short task may need only the coding tool's native workflow. Start with the default split skill catalog and expand it when needed. See the harness comparison and evaluation protocol.

To inspect overhead, start with auto skill audit --dir . --platform codex --json. Use explicit selection policies and replay cases before changing skill exposure, and auto telemetry harness to compare supplied native/current/reduced runs. The diagnostics guide includes runnable examples, unknown-value semantics, and read-only verification planning.

See multiagent coordination for current platform boundaries, dependency-aware runner behavior, and worker ownership validation. Native subagent availability alone does not establish a team lifecycle or workspace isolation in the active session.

auto doctor agents inventories installed runtimes without model calls. Explicit live collectors for Codex and OpenCode check native lifecycle evidence; auto telemetry team attributes supervisor/worker usage without adding parent rollups twice. See lifecycle checks and usage for execution boundaries, examples, and the recorded live results.

What is checked: CLI gates validate specific artifacts, configuration, and results when invoked and configured. Skill instructions guide planning, TDD, and review; they do not prove that an agent followed every step. A passing gate is evidence for its checked scope, not a guarantee that an application is ready for production.

🎬 See It In Action

# Brainstorm with 3 AI models debating each other
/auto idea "Add OAuth2 with Google and GitHub providers" --multi --ultrathink
One command does the rest — plan, build with 17 agents, ship with docs
/auto dev "Add OAuth2 with Google and GitHub providers"

Or if you prefer step-by-step control:

/auto plan "Add OAuth2 with Google and GitHub providers" --auto --multi --ultrathink
/auto go SPEC-AUTH-001 --auto --loop --team
/auto sync SPEC-AUTH-001

🐙 Pipeline ─────────────────────────────────────────────
  ✓ Phase 1:   Planning         planner decomposed 5 tasks
  ✓ Phase 1.5: Test Scaffold    12 failing tests created (RED)
  ✓ Phase 2:   Implementation   3 executors with disjoint file ownership
  ✓ Phase 3:   Testing          coverage: 62% → 91%
  ✓ Phase 4:   Review           TRUST 5: APPROVE | Security: PASS
  ───────────────────────────────────────────────────────
  ✅ 5/5 tasks │ 91% coverage │ 0 security issues │ 4m 32s

The pipeline output above is illustrative, not a benchmark. Completion depends on the project’s acceptance criteria and executed checks.

⭐ Star History

😤 The Problem

You're using AI coding tools. They're powerful. But...

• 🔄 Platform lock-in — Switch from Claude to Codex? Rewrite all your rules and prompts from scratch.
• 🎲 Hope-driven development — "Add auth" → AI writes code, skips tests, ignores security, forgets docs. Maybe it works.
• 🧠 Amnesia — Next session, the AI forgets every decision. "Why did we use this pattern?" → silence.
• 👤 Solo agent — One model, one context, one shot. Multi-file refactoring? Good luck.

🧠 The Philosophy: AX — Agent Experience

AX is not "AI Transformation." AX is Agent Experience — how AI agents perceive, navigate, and operate within your codebase. Just as UX designs for users and DX designs for developers, AX designs for agents.

flowchart LR
    UX["🧑 UX\nUser Experience"]
    DX["👩‍💻 DX\nDeveloper Experience"]
    AX["🤖 AX\nAgent Experience"]
UX -->|"designs for"| U["Users"]
    DX -->|"designs for"| D["Developers"]
    AX -->|"designs for"| A["AI Agents"]
style AX fill:#ff6b6b,stroke:#c92a2a,color:#fff

Most AI coding tools are designed around a simple model: you prompt, it responds.

Autopus starts from a different question: What if the agent is the primary audience of your project's documentation?

Think about onboarding a new engineer. You wouldn't hand them a blank editor and say "build the auth system." You'd give them:

• An architecture overview so they understand the system
• Coding conventions so their code fits in
• Decision history so they don't repeat past mistakes
• A review process so mistakes get caught before shipping

Autopus is a harness — a structured environment that gives agents the context, constraints, and workflows they need to produce code that a senior engineer would approve. Not through hope. Through design.

Of the agents. By the agents. For the agents.

flowchart TB
    subgraph OF ["🧬 Of the Agents"]
        direction TB
        O1["17 specialized agents\nform a software team"]
        O2["Planner · Executor · Tester\nReviewer · Architect · ..."]
    end
subgraph BY ["⚡ By the Agents"]
        direction TB
        B1["Agents run the pipeline\nautonomously"]
        B2["Self-healing gates\nParallel worktrees\nMulti-model debate"]
    end
subgraph FOR ["🎯 For the Agents"]
        direction TB
        F1["Every file, rule, and doc\nis designed for agents to parse"]
        F2["Project-defined limits · opt-in @AX\nStructured Lore · SPEC format"]
    end
OF --> BY --> FOR
style OF fill:#4c6ef5,stroke:#364fc7,color:#fff
    style BY fill:#7950f2,stroke:#5f3dc4,color:#fff
    style FOR fill:#f06595,stroke:#c2255c,color:#fff

| Principle | What It Means | |-----------|--------------| | Of the Agents | 17 specialized agents form a real engineering team — planner, executor, tester, reviewer, security auditor, and more. Not one chatbot. A team. | | By the Agents | Agents run the pipeline autonomously — self-healing quality gates, parallel worktrees, multi-model debate. Humans set the goal; agents handle the rest. | | For the Agents | Every file, rule, and document is designed to be parsed by agents, not just read by humans. Structure over prose. That's AX. | | Every Session is Day One | Agents lose all context between sessions. The harness provides institutional memory — architecture, decisions, conventions — so they start informed, not blank. |

🐙 Autopus doesn't make agents smarter. It makes them informed. That's AX.

🔥 What Makes Autopus Different

📏 Code That Agents Can Actually Read

File size alone does not establish cohesion or correctness. Autopus reports large source files, but enforces a ceiling only when the project sets a positive architecture.max_file_lines. Absent or 0 is advisory; keep cohesive code together and split by real responsibility. Repository-specific CI limits remain authoritative.

❌ Traditional:
   service.go (1,200 lines) → Agent loses context halfway through
✅ Autopus:
   service.go       (180 lines)  Handler logic
   service_auth.go  (120 lines)  Auth middleware
   service_repo.go  (150 lines)  Data access
   → Every file fits in one context window. Every file has one job.

This isn't just about file size. The entire harness is agent-readable by design:

| Layer | How It's Agent-Friendly | |-------|------------------------| | Rules | Structured markdown with IMPORTANT markers — agents parse, not skim | | Skills | YAML frontmatter with triggers — agents auto-activate the right skill | | Docs | Tables over paragraphs, checklists over prose — parseable, not readable | | Code | Clear responsibilities and explicit project limits; no universal line-count ceiling |

🐙 Human-readable is a bonus. Agent-readable is the requirement.

🤖 AI Agents That Form a Team, Not a Chatbot

Autopus doesn't give you one AI assistant — it gives you a software engineering team of 17 specialized agents with defined roles, quality gates, and retry logic.

🧠 Planner        →  Decomposes requirements into tasks
⚡ Executor ×N    →  Implements code in parallel worktrees
🧪 Tester         →  Writes tests BEFORE code (TDD workflow instruction)
✅ Validator       →  Checks build, lint, vet
🔍 Reviewer       →  TRUST 5 code review
🛡️ Security       →  OWASP Top 10 audit
📝 Annotator      →  Documents code with @AX tags
🏗️ Architect      →  System design decisions
🔬 Deep Worker    →  Long-running autonomous exploration + implementation
... and 7 more

⚔️ AI Models That Debate Each Other (--multi)

One model has blind spots. Three models catch each other's mistakes.

Every AI model has its own strengths and biases — Claude is thorough but verbose, Codex is fast but sometimes shallow, Gemini brings a different perspective entirely. When you use --multi, they don't just work in parallel — they review, challenge, and build on each other's ideas.

# Add --multi to any command for multi-model intelligence
/auto idea "new feature" --multi          # 3 models brainstorm → cross-pollinate → ICE score
/auto plan "new feature" --multi          # 3-model read-only planning advisory → one SPEC writer → independent review
/auto go SPEC-ID --multi                  # 3 models debate your code review

flowchart TB
    C["🔍 Claude\nIndependent Analysis"] --> D["⚔️ Cross-Pollination\nEach model sees others' ideas"]
    X["🔍 Codex\nIndependent Analysis"] --> D
    G["🔍 Gemini\nIndependent Analysis"] --> D
    D --> R["🔄 Round 2\nAcknowledge · Integrate · Risk"]
    R --> J["🏛️ Blind Judge\nAnonymized scoring"]

Why this matters:

• A bug that Claude misses, Codex catches. An edge case Codex ignores, Gemini flags.
• Ideas that one model would never generate emerge from cross-pollination.
• The blind judge scores anonymized results — no model favoritism.
• Research shows multi-agent debate produces higher-quality outputs than any single model alone.

💡 /auto dev enables --multi by default. Every plan gets multi-model review. Every code review gets cross-checked. You don't have to think about it.

4 strategies: Consensus (merge agreements) · Debate (adversarial review + judge) · Pipeline (chain outputs) · Fastest (first wins)

🔁 Self-Healing Pipeline (RALF Loop)

Quality gates don't just fail — they fix themselves and retry.

flowchart LR
    R["🔴 RED\nRun Phase"] --> G["🟢 GREEN\nGate Check"]
    G -->|PASS| Done["✅ Next Phase"]
    G -->|FAIL| F["🔧 REFACTOR\nFix Issues"]
    F --> L["🔁 LOOP\nRetry"]
    L --> R
    L -.->|"3× no progress"| CB["⛔ Circuit Break"]
style R fill:#ff6b6b,stroke:#c92a2a,color:#fff
    style G fill:#51cf66,stroke:#2b8a3e,color:#fff
    style F fill:#ffd43b,stroke:#f08c00,color:#000
    style L fill:#748ffc,stroke:#4263eb,color:#fff
    style CB fill:#868e96,stroke:#495057,color:#fff

/auto go SPEC-AUTH-001 --auto --loop

🐙 RALF [Gate 2] ──────────────────
  Iteration: 1/5 │ Issues: 3
  → spawning executor to fix golangci-lint warnings...
🐙 RALF [Gate 2] ──────────────────
  Iteration: 2/5 │ Issues: 3 → 0
  Status: PASS ✅

RALF = RED → GREEN → REFACTOR → LOOP — TDD principles applied to the pipeline itself. Built-in circuit breaker prevents infinite loops.

🌳 Parallel Agents in Isolated Worktrees

The worktree execution path isolates executors in separate Git working directories. Codex native workers share one cwd/filesystem: assign disjoint files and serialize overlapping edits. The following example applies to the worktree path.

Phase 2: Implementation
  ├── ⚡ Executor 1 (worktree/T1) → pkg/auth/provider.go     ✓
  ├── ⚡ Executor 2 (worktree/T2) → pkg/auth/handler.go      ✓
  └── ⚡ Executor 3 (worktree/T3) → pkg/auth/middleware.go    ✓
Phase 2.1: Merge (task-ID order)
  ✓ T1 merged → T2 merged → T3 merged → working branch

The worktree path supports up to 5 concurrent worktrees. File ownership and ordered integration reduce conflicts; merges still require verification. Native worker capacity depends on the platform and available runtime limits.

📜 Lore: Your Codebase Never Forgets

Every commit captures the why, not just the what. Queryable forever.

feat(auth): add OAuth2 provider abstraction
Why: Need Google + GitHub support, extensible for future providers
Decision: Interface-based abstraction over direct SDK usage
Alternatives: Direct SDK calls (rejected: too coupled)
Ref: SPEC-AUTH-001
🐙 Autopus <[email protected]>

9 structured trailers. Query with auto lore query "why interface?". Stale decisions auto-detected after 90 days.

🧪 Autonomous Experiment Loop

Let AI iterate autonomously — measure, keep or discard, repeat.

/auto experiment --metric "go test -bench=BenchmarkProcess" --direction lower --max-iter 5

🐙 Experiment ───────────────────────
  Iter 1: baseline  │ 1200 ns/op
  Iter 2: optimize  │  850 ns/op  ✓ keep (29% improvement)
  Iter 3: refactor  │  900 ns/op  ✗ discard (regression)
  Iter 4: cache     │  620 ns/op  ✓ keep (27% improvement)
  ─────────────────────────────────────
  Result: 1200 → 620 ns/op (48% improvement)

Built-in circuit breaker prevents runaway iterations. Simplicity scoring penalizes over-complex solutions. Each iteration is a git commit — easy to review or revert.

⚠️ Status: Experimental — CLI commands (auto experiment) are available but skill-level integration is in progress. Core iteration loop works; full pipeline integration is coming.

🧠 Pipeline That Learns From Failures

Autopus pipelines don't just fail — they remember why and prevent the same mistake next time.

Gate 2 FAIL: golangci-lint — unused variable in pkg/auth/
→ Auto-recorded to .autopus/learnings/pipeline.jsonl
→ Next /auto go: learning injected into executor prompt
→ Same mistake never repeated

Every pipeline failure is captured as a structured learning entry. On the next run, relevant learnings are automatically injected into agent prompts — giving your pipeline institutional memory across sessions.

🏥 Post-Deploy Health Check

Deploy first, verify immediately. canary runs build verification, E2E tests, and browser health checks against your live deployment.

/auto canary                          # Build + E2E + browser auto-verification
/auto canary --url https://myapp.com  # Target a specific deployment URL
/auto canary --watch 5m               # Repeat every 5 minutes
/auto canary --compare                # Compare against previous canary report

Generates canary.md with full diagnostics — build status, test results, accessibility scores, and screenshot diffs.

🔀 Smart Model Routing

Not every task needs Opus. Autopus analyzes message complexity and routes to the right model automatically.

Simple query     → Haiku  (fast, cheap)
Code review      → Sonnet (balanced)
Architecture     → Opus   (deep reasoning)

No configuration needed — the router evaluates token count, code complexity, and domain signals to pick the optimal model. Override anytime with --quality ultra.

🔌 Provider Connection Wizard

Setting up AI providers shouldn't require reading docs. auto connect walks you through a 3-step guided setup.

auto connect         # Interactive wizard: server auth → workspace → OpenAI OAuth
auto connect status  # Deterministic local verify/readiness summary

The current release authenticates with the Autopus server, saves the selected workspace, and completes the OpenAI OAuth handoff. Use auto connect status or auto desktop status --json to verify the saved local state.

Desktop runtime ownership note:

• The packaged autopus-desktop-runtime source/build/release provenance now lives in autopus-desktop/runtime-helper/.
• ADK keeps auto connect, auto desktop ..., and auto worker ... as harness or compatibility surfaces, but normal desktop runtime shipping no longer depends on an autopus-adk checkout.

🤖 ADK Worker — Local Agent Execution

ADK Worker runs A2A + MCP hybrid tasks locally with browser login, JWT refresh, and direct platform connectivity. No separate bridge daemon or worker API key exchange is required for the default production path.

What it is for:

• Connecting a local workspace to the Autopus platform worker loop
• Receiving platform-dispatched tasks and executing them with local tools
• Reusing the same security, budget, and audit rails as the main harness

• If you're here for auto init, Codex @auto ..., or OpenCode /auto ..., you can ignore Worker for now
• auto worker ... is an optional advanced surface that is still being rolled out and documented

💰 Iteration Budget Management

Workers don't run forever. Each executor gets a tool-call budget — preventing runaway agents while ensuring enough room to complete complex tasks.

📦 Context Compression

As pipelines progress through phases, earlier context gets compacted automatically into a fixed schema: Goal, Constraints, Progress, Decisions, Relevant Files, Next Steps, and Critical Context. Tool calls and results are pruned as pairs, unsafe provider payload bodies are omitted, and every applied compaction emits metadata with summary ids, source refs, reason codes, and budget/blocker state.

🔄 Pipeline That Never Dies

Crash mid-pipeline? Resume exactly where you left off.

/auto go SPEC-AUTH-001 --continue    # Resume from last checkpoint

YAML-based checkpoints save pipeline state after every phase. Stale detection prevents resuming outdated sessions. Combined with --auto --loop, you get a fully resilient autonomous pipeline.

🧪 E2E Scenarios from Your Code

Auto-generate and execute E2E test scenarios — no manual test writing needed.

auto test run                    # Run all scenarios
auto test run -s init --verbose  # Run a specific scenario

Autopus analyzes your codebase (Cobra commands, API routes, frontend pages) and generates typed scenarios with verification primitives (exit_code, stdout_contains, status_code, json_path, etc.). Incremental sync keeps scenarios up-to-date as code evolves.

🌐 Browser Automation — AI Agents That See and Click

AI agents can directly interact with web pages — open URLs, read accessibility trees, click elements, fill forms, and capture screenshots.

/auto browse --url https://example.com/settings

- @e1 heading "AI Settings"
@e2 button "Provider Mode"
@e3 switch "Auto Fallback" [checked]
@e7 button "Save"

📺 Live Agent Dashboard

On pane-capable team runtimes, each team member can get a terminal pane with real-time log streaming.

┌─ lead ──────────┬─ builder-1 ───────┐
│ Phase 1: Plan   │ T1: auth.go       │
│ 5 tasks created │ implementing...   │
├─ tester ────────┼─ guardian ────────┤
│ scaffold: 12    │ waiting...        │
│ RED state ✓     │                   │
└─────────────────┴───────────────────┘

Works in cmux and tmux. Plain terminals degrade gracefully to log-only output.

📚 Auto-Documentation with Context7

Before implementation, Autopus fetches latest library docs automatically — so agents never work with stale API knowledge.

Phase 1.8: Doc Fetch
  → Detected: cobra v1.9, testify v1.11
  → Fetched: 2 libraries (6000 tokens)
  → Injected into executor + tester prompts

Context7 MCP → WebSearch fallback → skip (never blocks pipeline). Adaptive token budget: 1 lib → 5000 tokens, 5 libs → 2000 tokens each.

🔧 More Power Tools

| Feature | Command | What It Does | |---------|---------|-------------| | Reaction Engine | auto react check/apply | Detects CI failures, analyzes logs, generates fix reports automatically | | Meta-Agent Builder | auto agent create / auto skill create | Scaffold custom agents and skills from patterns | | Hard Gate | auto check --gate | Enforce mandatory pipeline gates (mandatory/advisory modes) | | Self-Update | auto update --self | Verified binary update — atomic exchange on Darwin/Linux, .old recovery on Windows | | Cost Tracking | auto telemetry cost | Token-based pipeline cost estimation per model | | Issue Reporter | auto issue report | Auto-collect error context, sanitize secrets, create GitHub issues | | Signature Map | auto setup | Extract exported API signatures (Go + TypeScript) via AST analysis | | Test Runner Detection | auto init | Auto-detect jest, vitest, pytest, cargo test frameworks |

🌐 One Config, Five Platforms

auto init   # auto-detects supported installed AI coding CLIs

One autopus.yaml generates native configuration for every detected supported platform.

| Platform | What Gets Generated | |----------|-------------------| | Claude Code | .claude/rules/, .claude/skills//SKILL.md, .claude/agents/, .claude/workflows/, .claude/settings.json, CLAUDE.md | | Codex | .codex/skills/codex-/SKILL.md, .codex/agents/, .codex/hooks.json, .codex/config.toml, .agents/plugins/marketplace.json, .autopus/plugins/auto/, AGENTS.md | | Antigravity CLI | .agents/plugins/autopus/, .agents/hooks.json, plus retained .gemini/ / GEMINI.md compatibility surfaces | | OpenCode | .opencode/rules/, .opencode/agents/, .opencode/commands/, .opencode/plugins/, .agents/skills/, AGENTS.md, opencode.json | | Oh My Pi (OMP) | .omp/rules/autopus-*.md, .omp/skills//SKILL.md, .omp/commands/, optional .omp/extensions/ |

Antigravity discovers the workspace plugin directly. auto init and auto update do not import a project-rendered bundle globally, and no longer emit the unused .agents/commands/ mirror. Inspect the generated bundle with agy plugin validate .agents/plugins/autopus; this checks structure, not whether runtime permissions or hooks have executed. Native user permission settings are preserved.

The 2026-09-13 compatibility checks used Claude Code 2.1.263, Codex CLI 0.153.4, Antigravity CLI 1.1.26, OpenCode 1.18.7, and OMP 18.1.19. These are observed test versions, not a claim that every newer release or feature is verified. Codex 0.154.0 worktree support remains experimental; the harness does not silently enable experimental topology or replace user permission settings.

Codex note:

• Use $codex-auto-plan ..., $codex-auto-go ..., or another $codex-auto- skill immediately after auto init or auto update
• Install the generated local plugin from .agents/plugins/marketplace.json (.autopus/plugins/auto) to enable the friendlier @auto ... syntax
• The plugin provides the @auto ... router. Detailed workflows are unique native skills under .codex/skills/codex-/SKILL.md; Autopus does not generate repository .codex/prompts/ or markdown .codex/rules/
• Multi-agent mode uses [features.multi_agent_v2] with the six current collaboration tools and a shared cwd/filesystem; it does not use legacy send_input, resume_agent, or close_agent
• The requested spawned-worker ceiling is codex.agents.max_concurrent_threads in autopus.yaml (default 4, range 1–64); the coordinator is not included. auto update writes the requested value to .codex/config.toml. Namespace selection must be backed by CLI compatibility evidence; an unverified version uses the documented [agents] max_concurrent_threads_per_session with the assumption stated. Explicit harness settings survive regeneration. Host and account limits still take precedence.
• auto doctor separates the requested count and the value inspected on disk from the loaded-session and effective limits. Reading a project or user config file does not prove that an active session loaded it. Unobservable session limits remain unknown, with the inspection limitation reported. Start a new session after changing configuration; Autopus never interrupts active agents or equates this setting with local build/test concurrency.
• .codex/hooks.json is generated by default, while structural TOML merging preserves unrelated user config
• features.multi_agent is still a live native switch. Explicit true and false values, including user comments, survive regeneration and cleanup; equality with a current default is not ownership evidence.

• /auto ... and direct aliases like /auto-plan ... are generated under .opencode/commands/
• Native rule/agent/plugin files live under .opencode/, while reusable skills are published under .agents/skills/
• The default skills.compiler.mode: split publishes core skills and their required references. Opted-in long-tail bundles use .opencode/skills/; workflow-only rules remain readable without loading into every initial prompt.
• Helper workflows like /auto status, /auto map, /auto why, /auto verify, /auto secure, /auto test, /auto dev, and /auto doctor are generated as OpenCode-native command wrappers
• opencode.json now registers the managed hook plugin automatically, so .opencode/plugins/autopus-hooks.js is live immediately after auto init or auto update

• Rules are written flat as .omp/rules/autopus-.md. OMP scans each rule root non-recursively, so a nested rules/autopus/ directory would never reach the session; the autopus- filename prefix is the namespace instead
• Only the manifest-recorded autopus- files are ADK-owned. Your own rules in the same directory (.omp/rules/mine.md) are left untouched by auto update and auto platform remove omp
• auto init ignores .omp/rules/ as a directory pattern. A filename glob such as .omp/rules/autopus-*.md would silently remove every generated rule from OMP discovery, which is why the directory form is used. To track your own rule despite the ignore, run git add -f .omp/rules/mine.md (gitignore negation does not work inside an ignored directory) or keep it outside .omp/rules/
• OMP uses its priority-100 native .omp/skills//SKILL.md and .omp/commands/*.md roots. It does not register .agents/skills as a custom directory and does not create a base .omp/config.yml unless project-managed settings require one
• auto doctor verifies OMP 18.0.5 through version/help/config metadata and a provider-free RPC handshake. The handshake selects a bootstrap model locally but sends no prompt and performs no provider request

OMP role routing and context optimization (opt-in)

For everyday model setup, run:

auto quality

auto quality opens the agent model composition first (Per-agent model composition). Answer t there, or a target name such as claude-code, to configure one surface instead: the shared quality mode or one coding tool's agent models. Only tools whose generated agents carry a model are offered — Claude Code, Codex, and OMP; Antigravity CLI and OpenCode inherit the session model and are named as such instead of being silently omitted.

Claude Code / Codex: the wizard prints every agent with its relative tier and the concrete model that tier becomes on that tool, takes agent=tier edits (fable, opus, sonnet, haiku), previews the result, and on y stores the edits as a quality.presets. entry bound through quality.providers.. Each tool keeps its own preset, so moving Claude Code's executor to fable leaves Codex where it was. quality.default never changes. A customized balanced or ultra preset is not overwritten: the editor refuses that name and cancels after three refusals. Run auto update (or auto quality --apply) to regenerate the agent files.

OMP: choose balanced/ultra → GPT/Claude, or custom to pick an installed model per bundled agent. The custom path still anchors a family for the agents you do not pin, lists the installed catalog with each model's thinking levels, and labels every prompt with the capability that agent's route requires. A model the catalog says cannot serve that capability is refused at the prompt with the models that can. Review the compact agent/model/thinking table and type y to apply. This line editor keeps OMP profiles in both modes; the composition step's OMP tab in the default autopus mode pins agents without a profile instead (Per-agent model composition).

Enter, n, or EOF at confirmation cancels without changes; --apply is not required. Existing agent overrides and multi-provider review settings are preserved. An explicitly defined custom profile keeps its own model families. Start a new OMP session after applying.

Advanced and automation commands remain available:

auto platform omp models                 # installed model catalog
auto platform omp profile apply balanced --family gpt --plan
auto platform omp profile apply balanced --family gpt
auto platform omp explain
auto status --platform omp

When the installed OMP catalog lacks family, capability, or authorization metadata, models still returns exact native selectors and thinking support as a degraded display-only result. Automatic profile generation and strict routing remain blocked with catalog_metadata_insufficient; Autopus does not infer those fields or inspect credentials. A pre-existing explicit profile may instead select catalog_trust: operator-attested: Autopus first runs the same bounded strict probe, then uses only the exact intersection of native selectors and operator declarations while keeping auth/keyless unobserved.

Activation verifies every projected @role through an OMP RPC get_state session loaded with the generated overlay. It sends no prompt and makes no model-provider request; the resulting provider/model/thinking map is bound into the receipt and independently rechecked by explain/doctor.

From v0.50.126 OMP serves the 17 Autopus agents by default (SPEC-MODELUX-003, SPEC-REA-001). Generation writes .omp/agents/.md for every canonical agent, owned by the OMP manifest and carrying no model field; thinkingLevel is the agent's declared effort and appears only when no task.agentModelOverrides route names that agent. It also claims task.disabledAgents: [scout, security-reviewer, sonic, designer, librarian] in the project .omp/config.yml, which plain omp reads: every bundled agent but task across the omp releases Autopus supports (18.6.1 bundles the first three, 17.2.7 also designer and librarian), and a name the installed omp does not bundle is an inert filter entry. The bundled task agent stays enabled because an unnamed dispatch runs it, and the generated reviewer replaces the bundled one with the output schema of the omp 18.6.1 reviewer, so /review keeps its verdict. With a role profile, routes are written as task.agentModelOverrides keyed by the 17 names and task (task follows a task pin, then a planner pin, then the profile's planner route) through the existing activation, attestation, readback, and rollback; without a profile, pins alone (below) route only the pinned agents, and task through its own or planner's pin, and with no pin every agent inherits the session model.

auto update previews the move once — + .omp/agents/.md lines, task.disabledAgents: scout, security-reviewer, sonic, designer, librarian, and OMP now uses the 17 Autopus agents; set role_model_policy.agent_source: native to go back during v0.50.126. — and performs it in the OMP adapter's one transaction without writing autopus.yaml. An .omp/agents/.md the manifest does not record is a user file and stays byte-identical (.omp/agents/.md is a user file; left unchanged). A task.disabledAgents you set to another value is user-owned: Autopus leaves it, prints task.disabledAgents in .omp/config.yml is user-owned; scout, security-reviewer, sonic, designer, and librarian stay enabled, and doctor reports agents:disabled_agents_user_owned as degraded; only auto clean drops that mark.

Doctor's OMP agent catalog turns degraded with agents:autopus_agent_user_file while a canonical .omp/agents/.md is a user file, because OMP then runs that file instead of the Autopus definition. A project .omp/config.yml the managed parser cannot read safely — a symlink, invalid YAML, several documents, an alias, a flow-style mapping, or a lone CR, NEL, LS, or PS line break — is never written: auto update prints task.disabledAgents was not written: .omp/config.yml cannot be read safely (a symlink, invalid YAML, several documents, an alias, a flow-style mapping, or a lone CR, NEL, LS, or PS line break); scout, security-reviewer, sonic, designer, and librarian stay enabled instead of the task.disabledAgents: … preview line, and doctor reports agents:project_config_unclaimable, a state distinct from a user-owned value. When a ledger already claims the key and the file then gains such a line break, the file and the ledger stay as they are, auto update prints task.disabledAgents is left as last written: …, and auto clean refuses with project_config_unclaimable until the file reads cleanly. Once no ledger claims .omp/config.yml, ADK keeps none of the backups its transactions recorded of that file except one: the rollback artifact of the newest committed transaction that released the ledger, applied to the config as that release left it. It stays under .autopus/backup/ until the next release replaces it, so a release can still be undone by hand; a release that deleted a config ADK had created leaves none, and auto clean restores from the verified preimage and leaves no rollback artifact of the config.

role_model_policy.agent_source: native restores the behavior described below for v0.50.126 only; the key and the native path are planned for removal in v0.50.127. Any other value fails to load with role_model_policy.agent_source_invalid, and the key alone configures no role model policy. Roll back with this key, not with an older binary: auto older than v0.50.126 cannot read an autopus.yaml that sets agent_source or quality.presets.*.efforts, and v0.50.125 rejects the project ownership ledger (.autopus/omp-model-project-ownership-v1.json) once it carries the new agent-surface fields. The next two paragraphs describe agent_source: native.

auto init writes no agent definition for OMP. OMP registers its own bundled agents (task, scout, reviewer, security-reviewer, sonic) and resolves a task agent by exact name, so a generated .omp/agents/.md would only shadow the bundled one. A role profile binds models through task.agentModelOverrides instead, and the 17 ADK work roles collapse onto those five agents. auto platform omp explain and auto status --platform omp show one row per bundled agent with its role/capability provenance and effective selector; a project file at .omp/agents/.md is reported as native_agent_shadowed.

Several role keys can land on one bundled agent. The representative role decides — task follows planner, scout follows explorer, sonic follows validator — and every plan row, explain row, and receipt entry reports the governing key, so a pre-cutover policy that names all 16 roles keeps working and the applied entry stays visible. A set with no representative row has nothing to rank it and is refused with omp_native_agent_conflict naming the entries to reconcile.

OMP balanced: GPT or Claude family

Select the OMP mode and family together with profile apply balanced --family gpt|claude. The stored family names are openai and anthropic; both canonical names are also accepted. --plan previews the bundled agents, their requested/effective model and thinking, candidate order, fallback attempts, and blockers without writing configuration or activating a profile. Apply verifies the same routes through the installed OMP catalog and provider-free RPC readback.

| Bundled agent (representative role) | GPT balanced | Claude balanced | |---|---|---| | task (planner), reviewer, security-reviewer (security-auditor) | GPT-6 Astra max | Claude Fable 5.1 max | | scout (explorer), sonic (validator) | GPT-5.6 Luna max | Claude Sonnet 5 high |

Ordinary reviewers follow the selected family. Multi-provider review remains a separate orchestra.providers policy: changing this profile preserves its models and judge. For top-model review, keep Fable max, Astra max, and the selected Gemini model's highest supported thinking level (high for Gemini 3.1 Pro; it does not expose max).

Balanced has no implicit lower-model fallback. Missing models or unsupported thinking block apply before writes, and a blocked preview returns nonzero with per-agent reasons. Native retry.modelFallback is false when the profile has no explicit fallback chains.

Override one agent without copying the full profile:

auto platform omp profile apply balanced --family gpt --agent executor=openai-codex/gpt-6-astra:max --plan
auto platform omp profile apply balanced --family gpt --agent executor=openai-codex/gpt-6-astra:max
auto platform omp profile apply balanced --agent executor=inherit

Repeat --agent for multiple agents. Pins are stored in role_model_policy.agents..candidates and remain explicit overrides across profile/family changes until cleared with =inherit. On a native catalog without semantic metadata, a pin must have an exact family declaration in the shipped built-in profiles or the selected custom profile; arbitrary unknown models are rejected.

This standard matrix is shared with native Claude Code and Codex. OMP's built-in routes remain independent of custom quality.presets.balanced.agents tiers; OMP overrides use role_model_policy.agents. Ultra and custom OMP profile definitions retain their existing behavior. An explicit role_model_policy.profiles.balanced definition still wins over the built-in; --family is rejected for such a custom definition instead of silently ignoring it. OMP profile selection does not change quality.default, standalone Claude/Codex settings, or the supervisor's native model roles. auto quality show reports OMP's independent selection.

OMP policies are provider-neutral and inactive until a named profile is selected. Prefer the non-destructive overlay mode. The built-in profiles use shipped operator-attested declarations intersected with the installed catalog. For a custom profile, use strict mode when semantic catalog metadata is available; otherwise use operator-attested mode only after reviewing its exact selectors, families, capabilities, and thinking levels. A ${NAME} placeholder anywhere in a role_model_policy model candidate — its selector, thinking, family, or a key, also when reached through a YAML alias — fails the load with role_model_policy.candidate_placeholder_unsupported, which names the path only, while placeholders in the root profile and family still load. Placeholder values can no longer change the YAML structure of autopus.yaml: a value that would — for example one that starts with [, {, !, &, or *, or holds : , where its placeholder is unquoted — or that holds a line break fails the load with an error that names the variable and never the value, as does an explicit tag other than !!str on a placeholder; written as '${NAME}', a placeholder passes any printable one-line value without ' as the exact string. Custom profile example:

role_model_policy:
  version: v1
  profile: omp-balanced
  profiles:
    omp-balanced:
      config_mode: overlay
      catalog_trust: operator-attested
      capabilities:
        deep_reasoning:
          required: true
          candidates:
            - selector: provider-a/reasoner
              family: family-a
              thinking: high
        coding_tool_use:
          required: true
          candidates:
            - selector: provider-a/coder
              family: family-a
              thinking: medium
        fast_validation:
          required: true
          candidates:
            - selector: provider-b/fast
              family: family-b
              thinking: medium
        vision_design:
          required: true
          candidates:
            - selector: provider-b/vision
              family: family-b
              thinking: high
        independent_dissent:
          required: true
          candidates:
            - selector: provider-b/reviewer
              family: family-b
              thinking: high
        deterministic_transform:
          required: true
          candidates:
            - selector: provider-a/transform
              family: family-a
              thinking: medium
      family_diversity:
        enabled: true
        roles: [autopus_reviewer, autopus_security_auditor]

• Candidate order is the fallback order. In strict mode, selector, family, and thinking must match observed semantic catalog metadata. In operator-attested mode, selectors must exist in the bounded native catalog and family/capability/thinking come only from the explicit profile; this does not claim that authentication will succeed. The placeholders above are not model recommendations.
• safety is optional. Add explicit approval_mode or isolation_mode values only after the installed-version capability probe reports support; omission leaves those keys unclaimed.
• Use project-managed only when the project intentionally owns the target OMP keys. Every claimed key needs the observed prior_fingerprint and complete: true; an array claim such as retry.fallbackChains also needs full_array_ownership: true.

omp_context_policy:
  profile: omp-safe-shadow
  profiles:
    omp-safe-shadow:
      history_mode: shadow
      memory_mode: off
      history_target_tokens: 1000
      fallback: canonical_full
      capability_policy: probe_required
      runtime_root_policy: isolated_task_owned
      mutation_scope: session_overlay
    omp-active-probed:
      history_mode: active
      memory_mode: off
      history_target_tokens: 1000
      fallback: canonical_full
      capability_policy: probe_required
      runtime_root_policy: isolated_task_owned
      mutation_scope: session_overlay

• Select omp-active-probed only when an exact capability probe succeeds, the runtime is task-owned (isolated_task_owned), and a fresh promotion attestation has been recomputed from at least 20 complete balanced AB/BA raw pairs and bound to the exact policy, session/binding, and canary digest. A missing, stale, mismatched, duplicate, or aggregate-only claim remains in shadow or is blocked. Use no_session only when no session runtime exists.
• The managed OMP bridge supports long-lived supervisor ACKs, exact canonical reinjection, and same-session compaction/rehydration through the current compaction.methodOrder contract. Generation alone still does not activate optimization: omp-active-probed remains fail-closed until a fresh task-owned runtime receipt proves the installed lifecycle and cleanup.
• Memory supports off or observation-only shadow. Shadow memory requires a memory_namespace; memory is never actively injected, and active receipts cannot claim memory injections or document omissions.
• Model resolution evidence is written to the gitignored runtime artifact .autopus/omp-model-resolution-v1.json. Task-scoped context evidence uses .autopus/runtime/omp-context///receipt.json.
• Run auto doctor (or auto doctor --json) to re-probe the installed CLI and configuration. Receipts must contain neither credentials, prompt bodies, nor absolute paths. Live provider transport checks can incur cost and run only with explicit auto doctor --provider-smoke opt-in; a stale receipt is not proof that a current canary passed.

Codex vs OpenCode

| Topic | Codex | OpenCode | |-------|-------|----------| | Primary command syntax | @auto ... | /auto ... | | Works immediately after auto init | $codex-auto- ... native skills | /auto ... and /auto- ... wrappers | | Extra install step | Install the generated local plugin from .agents/plugins/marketplace.json only when you want @auto ...; native $codex-auto- skills need no extra step | No extra router install step. opencode.json wires the managed plugin automatically | | Generated surface | .codex/skills/codex-*/, .codex/agents/, .codex/hooks.json, .codex/config.toml, .agents/plugins/marketplace.json, .autopus/plugins/auto/, AGENTS.md | .opencode/commands/, .opencode/agents/, .opencode/rules/, .opencode/plugins/, .agents/skills/, AGENTS.md, opencode.json | | What works well today | Native skills, local plugin routing, and Multi-Agent V2 Lead/Builder/Guardian coordination | Native command wrappers, task-based workers, and managed hook plugin wiring | | Current boundary | Multi-Agent V2 workers share one cwd/filesystem; parallel writers need disjoint ownership | Claude-style Agent Teams and Workflow primitives are not claimed | | Worker surface | spawn_agent, send_message, followup_task, targetless wait_agent, interrupt_agent, list_agents | OpenCode task(...) workers |

Split compiler note:

• skills.compiler.mode: split is the default. It publishes the core/dependency set and all /auto routes; optional recipes remain