autopus-adk

🐙 Autopus-ADK

A harness of the agents, by the agents, for the agents.

Make your AI coding tools (Claude Code, Codex, Antigravity CLI, OpenCode, Oh My Pi) work like a real engineering team — with planning, testing, code review, and security audits built in.

17 agents. 53 skills in the library, a compact default catalog. One config across platforms.

Paste this command into your AI coding agent's chat (Claude Code, Codex, OpenCode, etc.) — the agent will run it and set up everything automatically. Or run it directly in your terminal.

# 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"

Why Autopus · Core Workflow · Features · Pipeline · Security · Docs

🇰🇷 한국어

---

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

AI agents need the same things. The difference is that every session is their first day.

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.