Language / Sprache / Idioma: English · Deutsch · Português

AOS — BDB Agent OS

The operating system for AI agent harnesses.
One install: the same skills in nine harnesses. Subagents and the hook-enforced GO gate on Claude Code, Antigravity, Codex and OpenCode.

Built for event and media technicians, designers and managers, for builders of custom installations (show control, 3D, PCB and enclosure), and just as much for everyday coding of apps, tools and plugins. The skill library and the MCP servers cover both worlds.

AOS installs a curated skill library, a subagent roster, gate hooks and a runnable multi-agent build pipeline into every coding-agent harness on your machine.

npx -y @hybridlabor-api/aos@latest

_{Recommended: the full installer above. Alternatively, use the skills CLI:}

_{Skills use the open Agent Skills format (SKILL.md). AOS installs them for Claude Code, Google Antigravity, Codex CLI, OpenCode, Cursor, Windsurf, Roo Code / Cline, Aider and the AOS CLI, so all of them behave the same way.}

Why AOS

What you get

See Playbooks for guided workflows across these domains.

Quick start

See it in action

_{agenttrail. The live map of a multi-agent build while it runs. ▶ Full-quality video}

Plan Canvas. Annotate the plan in the browser, then approve it before any agent builds.	AO workspace. The pipeline monitor, plan to ship, with role and model routing per node.
AOS Store. Skills, agents and playbooks on 127.0.0.1:4322.	Codenotch. Agents running and busy per harness.

_{Fleet band. In Claude Code: gate mode, token-weather, and the sessions that wait for your GO.}

_{Installer. npx -y @hybridlabor-api/aos@latest: boot, pre-flight telemetry, then the setup menu. ▶ Full-quality video}

Skills at a glance

• /startcycle - linear build pipeline (Architect, TechLead, parallel build, Reviewer) with file hand-offs in production_artifacts/
• /startcycle-graph - dispatcher graph with durable state.json, Reviewer repair loop, quality gate and escalation
  • The dispatcher invokes the subagents architect, techlead, godmode-ui-ux, godmode-engineering, godmode-media-eventtech, reviewer and godmode-shipping; they never call each other
• /startcycle-graph-user - throwaway 2-4 node fan-out for any project, nothing persistent left behind
• /plan - draft, render in a browser canvas, annotate, await approval, then hand off
  • plan-canvas - local canvas where you annotate elements, chat and approve or request changes
  • plan-arbiter - compare competing plans from several agents and produce one recommended plan
• /bdbrainstorm - multi-agent brainstorm that ends in a hand-off to /startcycle-graph
  • /grill-me - relentless interview to sharpen a plan or design
  • bdbmediastorm - brainstorming for live event tech, show control and real-time media
• /playbooks - list every pb-* playbook with duration, difficulty and requirements, and start one
  • pb-bug-fix - GitHub issue to tested fix and PR; push and PR only after GO
  • pb-ship - triage, review and gate the day's PRs; merge only after GO
  • pb-release-aos - release AOS to npm through the release-please PR
  • pb-show-build - build a show across grandMA3, Resolume and TouchDesigner, offline first
  • pb-offer - draft a client offer priced from your price list; send only after GO
• factory-collect - Factory: collect and triage feedback, telemetry, errors and issue reports
  • factory-lookback - audit recurring problems across sources for systemic fixes
  • factory-review-prs - review a configured PR queue; approve and merge stay with you
  • factory-human-digest - read-only digest of what still needs a human decision
• gogate - show or explain the go-gate mode (hard, soft, off) and the time-limited grants; CLI: aos-gogate
• aos-a2a - list, send to and reply to live harness peers over A2A on localhost
  • master-session - supervise several sessions: roster, status requests, GO board; workers can be spawned through aos-acp
  • mcsc - delegate a task to another installed CLI harness (agy, OpenCode, Codex)
• agenttrail - live browser map of a multi-agent build; CLI: aos-trail
• aos-store - browse, preview and install skills and agents from a local web UI (aos store)
• memb-skill - local-first long-term memory engine (memB)
  • memb-ingest - ingest project files and conversation logs into memB
• openwiki-skill - initialize, update and visualize codebase wikis with OpenWiki
• synapse-integration-skill - BDB Synapse 3D codebase visualizer integration
• /doctor - check the machine and the current project, print suggested permissions.allow entries, write no settings
• aos-setup - bring a machine to a complete, verified AOS installation
  • aos-project-init - set up a project folder: slug, wiki, memory, Synapse map, AGENTS.md
• Godmodes - domain rulebooks
  • godmode-engineering - strict DDD, TypeScript strictness, Clean Architecture, 5-step debugging triage
  • godmode-ui-ux - brand discovery, Anti-Slop rules, DTCG design tokens, fluid motion
  • godmode-eventtech - show-control execution for grandMA3, Resolume, Unreal, Rhino, Vectorworks and Adobe MCP
  • godmode-hardware-pcb - schematics, PCB layout, KiCad and OpenSCAD enclosures with DFM/DRC/ERC sign-off
  • godmode-shipping - final gatekeeper: pre-launch checks, feature-flag rollouts, rollback planning
• Vendored helpers from BuilderIO/skills
  • read-the-damn-docs - forces a docs pass before coding third-party APIs from memory
  • stay-within-limits - respect 5-hour and weekly usage limits in long or parallel runs
  • quick-recap - end each response with a red/yellow/green status line

Full catalogs (every skill, subagent, playbook and MCP server) are in the collapsible lists under What's included.

What's new in v5

v5 changes how AOS gets onto a machine and how its parts talk to each other.

In progress, not claimed as shipped. agenttrail v2 control room, A2A intercom and a2abook, A2A spawn mode, skill-create and instinct-*.

The dispatcher graph

The graph is harness-neutral and runs on Claude Code's Dynamic Workflows, Antigravity's parallel execution, and any compatible agent harness.

%%{init: {"theme": "base", "themeVariables": {"lineColor": "#6e7681", "edgeLabelBackground": "#f6f1e8", "textColor": "#15171A", "clusterBkg": "#F7F4EC", "clusterBorder": "#B9B5AA", "titleColor": "#15171A", "primaryColor": "#FFFFFF", "primaryBorderColor": "#15171A", "primaryTextColor": "#15171A"}}}%%
flowchart TB
    subgraph SG[" "]
    direction TB
    U(["User"])
    A["<b>Architect</b><br/>System Plan"]
    T["<b>TechLead</b><br/>Capability Map"]
    UX["<b>UI_UX</b><br/>Frontend"]
    EN["<b>Engineering</b><br/>Backend"]
    ME["<b>Media_EventTech</b><br/>Creative"]
    R["<b>Reviewer</b><br/>QA"]
    S["<b>Shipping</b><br/>Gate"]

    U --> A --> T
    T --> UX & EN & ME
    UX & EN & ME --> R
    R --> S

    T -.->|reject| A
    R -.->|findings| UX
    S -.->|gate fail| EN
    R -.->|escalate| U
    end

    classDef plan fill:#E6F4EA,stroke:#1A7F3C,color:#15171A
    classDef build fill:#FFFFFF,stroke:#15171A,color:#15171A
    classDef gate fill:#1A7F3C,stroke:#1A7F3C,color:#FFFFFF
    classDef human fill:#F7F4EC,stroke:#5B6168,color:#15171A
    classDef store fill:#F7F4EC,stroke:#B9B5AA,color:#15171A
    linkStyle default stroke:#6e7681,stroke-width:2px

    style SG fill:#F7F4EC,stroke:#B9B5AA,color:#15171A

    class A,T plan
    class UX,EN,ME build
    class R,S gate
    class U human

_{Dispatcher graph. Architect and TechLead plan, three build nodes work in parallel, Reviewer and Shipping gate the result, and dashed edges route rejections and escalations.}

Install

Requirements. Node.js >= 20. macOS, Linux and Windows (PowerShell).

npx -y @hybridlabor-api/aos@latest

First run. The installer detects which harnesses are present, asks which to target and which tier (Pro MEDIA or Basic), copies the skills into each harness's skill directory, compiles the subagents, wires the hooks, merges the MCP configuration into each harness's own config file (existing entries are kept), and offers the optional modules listed below.

Every later run opens a menu instead:

Profiles and options

The gate and safety hooks are always installed. No profile or flag removes go-gate, go-token, go-grant, graph-gate, conventional-commits or env-file-protection. The OpenCode plugin is not affected by --no-hooks or minimal. Profile choices are saved in ~/.aos/v5-settings.json. Full reference: docs/install-options.md.

Non-interactive

npx -y @hybridlabor-api/aos@latest -y --platforms=2          # Claude only, all defaults
npx -y @hybridlabor-api/aos@latest -y --platforms=1,5 --mcps=none
npx -y @hybridlabor-api/aos@latest -y --modules=codebase-memory,styleseed
npx -y @hybridlabor-api/aos@latest --dry-run                 # print what would change

--platforms= values: 0 universal (all detected), 1 Antigravity, 2 Claude Desktop / Claude Code, 3 Cursor, 5 Codex CLI, 6 Windsurf, 7 Roo Code / Cline, 8 Aider, 10 AOS CLI. 4 (custom paths) needs the interactive menu. --mcps=<name,name>|all|none picks the MCP subset. --verbose and --no-intro do what they say.

Local project harness

Instead of installing into $HOME, drop only the dispatcher contract (.agents/, the gate hooks, the agent definitions, the /startcycle-graph workflow, the OpenCode plugin) into one repository:

cd your-project && npx -y @hybridlabor-api/aos@latest --project-harness -y

Supported harnesses

What gets written. The installer writes the following for each target. Paths are the defaults; the installer only writes to harnesses it actually detects.

Every install also writes the universal copy to ~/.agents/skills, which is what the AOS CLI and the skills CLI read.

OpenCode agents. The four godmode personas (godmode-ui-ux, godmode-engineering, godmode-media-eventtech, godmode-shipping) are compiled with mode: all, so they show up in the OpenCode agent picker and can drive a whole session, not only a subagent call. Two thin session-level roles are written next to them as mode: primary agents that load the matching skill: master-session (roster, status requests, GO board) and project-orchestrator (parallel agents across repositories through the AO daemon). Every other agent is compiled as mode: subagent.

Capability tiers

The harnesses do not get the same safety layer. The tier says what is actually wired, not what a harness could do in theory; per-row evidence is in docs/harness-capabilities.md.

Where a tier has no hook, nothing mechanical stops a guarded command: use a Tier 1 or 2 harness for anything that can push, publish or delete.

The pipelines

The contract lives in .agents/graph.md, the node roster in .agents/nodes.json, the executable dispatcher in .claude/workflows/startcycle-dispatch.mjs.

One rule: nodes never invoke each other. A dispatcher reads production_artifacts/state.json after each node returns and decides what runs next. There is no hand-off chain and no agent telling another agent to go. This design ensures context fidelity, single-place auditability of routing logic, and portability across harnesses.

Each node reads the plan and its own prior state, executes its work, writes its artifact and state fragments, and returns. The dispatcher merges per-node state fragments (state.d/<node>.json), evaluates edge predicates, and routes to the next node, or escalates to the user if a no-progress guard triggers (same blocking finding on the second repair cycle) or the iteration ceiling is reached.

%%{init: {"theme": "base", "themeVariables": {"lineColor": "#6e7681", "edgeLabelBackground": "#f6f1e8", "textColor": "#15171A", "clusterBkg": "#F7F4EC", "clusterBorder": "#B9B5AA", "titleColor": "#15171A", "primaryColor": "#FFFFFF", "primaryBorderColor": "#15171A", "primaryTextColor": "#15171A"}}}%%
flowchart LR
    subgraph SG[" "]
    direction LR
    U(["User"]) --> A("Architect") --> T("TechLead")
    T --> UX("Godmode_UI_UX") & EN("Godmode_Engineering") & ME("Godmode_Media")
    UX & EN & ME --> R("Reviewer") --> S("Shipping")
    T -.->|reject| A
    R -.->|findings| UX
    R -.->|needs_human| U
    end

    classDef plan fill:#E6F4EA,stroke:#1A7F3C,color:#15171A
    classDef build fill:#FFFFFF,stroke:#15171A,color:#15171A
    classDef gate fill:#1A7F3C,stroke:#1A7F3C,color:#FFFFFF
    classDef human fill:#F7F4EC,stroke:#5B6168,color:#15171A
    classDef store fill:#F7F4EC,stroke:#B9B5AA,color:#15171A
    linkStyle default stroke:#6e7681,stroke-width:2px

    style SG fill:#F7F4EC,stroke:#B9B5AA,color:#15171A

    class A,T plan
    class UX,EN,ME build
    class R,S gate
    class U human

_{Node roster. The seven nodes of the graph and the edges that send work back: reject, findings and needs_human.}

The three variants side by side

%%{init: {"theme": "base", "themeVariables": {"lineColor": "#6e7681", "edgeLabelBackground": "#f6f1e8", "textColor": "#15171A", "clusterBkg": "#F7F4EC", "clusterBorder": "#B9B5AA", "titleColor": "#15171A", "primaryColor": "#FFFFFF", "primaryBorderColor": "#15171A", "primaryTextColor": "#15171A"}}}%%
flowchart TB
    subgraph L["/startcycle (linear)"]
        direction LR
        L1("Architect") --> L2("TechLead") --> L3("parallel build") --> L4("Reviewer")
        L1 -. "production_artifacts/*.md" .-> L4
    end
    subgraph G["/startcycle-graph (durable)"]
        direction LR
        D{{"Dispatcher<br/>state.json"}}
        D --> N1("node") --> D
        D --> N2("node") --> D
        D --> Q("quality gate")
        D -. "no progress / ceiling" .-> H(["Human"])
    end
    subgraph F["/startcycle-graph-user (throwaway)"]
        direction LR
        F0("main session") --> W1("worker") & W2("worker") --> F3("review pass")
    end
    L ~~~ G ~~~ F

    classDef plan fill:#E6F4EA,stroke:#1A7F3C,color:#15171A
    classDef build fill:#FFFFFF,stroke:#15171A,color:#15171A
    classDef gate fill:#1A7F3C,stroke:#1A7F3C,color:#FFFFFF
    classDef human fill:#F7F4EC,stroke:#5B6168,color:#15171A
    classDef store fill:#F7F4EC,stroke:#B9B5AA,color:#15171A
    linkStyle default stroke:#6e7681,stroke-width:2px

    class L1,L2,F0 plan
    class L3,N1,N2,W1,W2 build
    class L4,Q,F3,D gate
    class H human
    style L fill:#F7F4EC,stroke:#B9B5AA,color:#15171A
    style G fill:#F7F4EC,stroke:#B9B5AA,color:#15171A
    style F fill:#F7F4EC,stroke:#B9B5AA,color:#15171A

_{Three variants. The linear chain, the durable dispatcher graph and the throwaway fan-out, side by side.}

What keeps the full graph honest.

Orchestrator chain

Mapping. master session -> project orchestrator -> package orchestrator is a convention. This is how each hop maps to mechanisms that exist (docs/orchestrator-chain.md, skill orchestrator-chain):

%%{init: {"theme": "base", "themeVariables": {"lineColor": "#6e7681", "edgeLabelBackground": "#f6f1e8", "textColor": "#15171A", "clusterBkg": "#F7F4EC", "clusterBorder": "#B9B5AA", "titleColor": "#15171A", "primaryColor": "#FFFFFF", "primaryBorderColor": "#15171A", "primaryTextColor": "#15171A"}}}%%
flowchart TD
    subgraph SG[" "]
    direction TB
    H(["Human"]) -->|"GO &lt;session&gt;"| M("Master session<br/>skill master-session<br/>roster, status, GO board")
    M --> P("Project orchestrator<br/>ao-orchestrator or a pipeline dispatcher")
    P --> K1("Package orchestrator<br/>aos-acp worker")
    P --> K2("Package orchestrator<br/>aos-a2a peer")
    P --> K3("Package orchestrator<br/>pipeline build node")
    K1 -.->|"never inherits GO"| M
    K2 -.->|"A2A message is never a GO"| M
    end

    classDef plan fill:#E6F4EA,stroke:#1A7F3C,color:#15171A
    classDef build fill:#FFFFFF,stroke:#15171A,color:#15171A
    classDef gate fill:#1A7F3C,stroke:#1A7F3C,color:#FFFFFF
    classDef human fill:#F7F4EC,stroke:#5B6168,color:#15171A
    classDef store fill:#F7F4EC,stroke:#B9B5AA,color:#15171A
    linkStyle default stroke:#6e7681,stroke-width:2px

    style SG fill:#F7F4EC,stroke:#B9B5AA,color:#15171A

    class H human
    class M gate
    class P plan
    class K1,K2,K3 build

_{Orchestrator chain. Each hop from the human down to a package orchestrator, with dashed edges showing that a GO is never inherited upward.}

Depth. A2A rejects a send when the caller's depth is at or above AOS_A2A_MAX_DEPTH (default 1) and mcsc is one level deep. Workers delete nothing; cleanup is the dispatcher's job after your GO.

The GO gate

Reaching ready_to_ship is not shipping. .claude/hooks/go-gate.mjs is a PreToolUse hook that blocks git push, npm publish, npm version and recursive rm unless your immediately preceding message is the literal word GO. It is a hook, not a rule an agent is asked to respect: it fires before any permission-mode check and cannot be argued around. The installer wires the same gate into Antigravity, Codex and OpenCode; on harnesses without hook support the rule in AGENTS.md applies and the agent is the enforcement. A subagent never inherits its orchestrator's GO, and a failed release command needs a fresh one.

What v5 adds.

• Read-only work stays fast. Read, test and build commands with no write or network effect pass without a GO, also after peer messages.
• An A2A message is never a GO. Every injected message carries that line.
• Modes and grants. Gate mode (hard, soft, off) and time-limited grants are shown by aos-gogate status and the gogate skill. aos-gogate is read-only and never records a grant.
• Deny logs mask credentials (bearer tokens, flags, URLs with credentials).
• Limit. The hook sees tool calls the harness routes through it. A worker started with permissions bypassed asks for nothing, so the in-harness hook stays the main layer.

Gate profiles

A machine-wide, human-set profile widens or narrows what the gate asks for. .claude/hooks/go-gate.mjs reads it through .claude/hooks/gate-profile.mjs, so every harness that uses the shared go-gate (Claude Code, OpenCode, Codex, agy) honours it.

aos-gate status                       # profile, time left, last change
aos-gate profile work --for 24h       # needs a real TTY; refused inside a harness session
aos-gate profile strict               # no confirmation needed

• Release class (still needs a GO under work): push to the default branch, main/master or release/*, npm publish, npm version, npm dist-tag add/rm, gh pr merge, gh release create, recursive delete, bulk move out of home and delete outside the own worktree.
• Hard blocks stay in every profile: writes to the gate store or its config, delete paths built from HOME, ~ or environment variables, recursive delete outside the own worktree, edits to the gate hooks and the settings that register them.
• Fail closed: a missing, unreadable, symlinked, oversized, wrongly owned or wrong-mode (not 0600) config, a corrupt or expired file, or a work/off profile without expiry all read as strict. Config: ~/.aos/gate/config.json.
• Loosening requires typing back a random word on the TTY.
• Accepted residual: code running as your own user can write the profile file directly. See docs/gate-residuals.md.

Playbooks

A playbook is a skill with kind: playbook that turns a recurring job into a guided run with a fixed contract. The 35 pb-* playbooks ship with the skills; list and start them with /playbooks (it runs list-playbooks.mjs and prints name, time, difficulty and requirements for each). There is no per-playbook command: you name the playbook.

What a playbook declares. Its frontmatter names trigger phrases, inputs, requires (skills, subagents, MCP servers, store items), go_points, outputs, a verify check, difficulty and est_time. The body is a numbered step list. Each step names the skill or agent it uses, its input, the artifact it writes and the check that says it is done.

How a run works.

• One session by default. The main session walks the steps and calls the required skills. Every step appends one line to a run log (production_artifacts/pb-<name>-<date>.md, never committed).
• Subagents where it matters. Steps marked (agent) run a subagent: reviewer in pb-bug-fix, pb-ship and pb-release-aos; architect, techlead and reviewer in pb-harness-work, pb-idea-to-launch and pb-redesign-app; security-reviewer and silent-failure-hunter in pb-security-sweep; opensource-forker and opensource-sanitizer in pb-open-source. On a harness without subagents the main session reads the agent file and runs the same contract inline. pb-master goes one step further and runs a control session over several Claude Code, Codex or OpenCode sessions.
• GO points are part of the contract. A [GO] step stops with WAITING FOR GO: <step> until you type GO; one GO covers one step, once. The go-gate hook is only the backstop. A failed check stops the run and is written into the log; nothing is retried silently.
• One command, not one per playbook. There is a single playbooks command that lists them; after that you name the playbook. How to reach it differs per harness:

%%{init: {"theme": "base", "themeVariables": {"lineColor": "#6e7681", "edgeLabelBackground": "#f6f1e8", "textColor": "#15171A", "clusterBkg": "#F7F4EC", "clusterBorder": "#B9B5AA", "titleColor": "#15171A", "primaryColor": "#FFFFFF", "primaryBorderColor": "#15171A", "primaryTextColor": "#15171A"}}}%%
flowchart LR
    subgraph SG[" "]
    direction LR
    I[("Issue")] --> C1("Root cause<br/>+ test")
    C1 --> C2("Fix")
    C2 --> R("Review")
    R -.->|findings| C2
    R --> C3("PR")
    C3 --> G{{"GO"}}
    G -->|yes| C4("Push")
    end

    classDef plan fill:#E6F4EA,stroke:#1A7F3C,color:#15171A
    classDef build fill:#FFFFFF,stroke:#15171A,color:#15171A
    classDef gate fill:#1A7F3C,stroke:#1A7F3C,color:#FFFFFF
    classDef store fill:#F7F4EC,stroke:#B9B5AA,color:#15171A
    linkStyle default stroke:#6e7681,stroke-width:2px

    style SG fill:#F7F4EC,stroke:#B9B5AA,color:#15171A

    class I store
    class C1,C3 plan
    class C2,C4 build
    class R,G gate

_{pb-bug-fix. The issue is the contract, the test comes before the fix, the Reviewer sees only the diff and the issue, and the push waits for your GO.}

Factory

What it is. Nine experimental skills adapted from BuilderIO/skills that turn feedback, telemetry, errors, issues and pull requests into a repeatable review loop: factory (the schedule and policy that hosts the others), factory-collect, factory-lookback, factory-review-prs, factory-human-digest, plus the delivery-side factory-ship, factory-babysit-pr, factory-watchdog and factory-recover. In AOS they report and draft; every external write waits for your GO. plan-arbiter ships alongside them for comparing competing plans.

The review loop.

How to run

• Invoke by name. Ask the agent to run the skill, for example factory-collect; each SKILL.md carries a "Use when" trigger. Start by hand and read the report before enabling anything scheduled.
• Configure. .agent-factory/config.yaml, read by all of them. Keys named in the skills: workflows.collect.sources, workflows.collect.implement, workflows.lookback, workflows.lookback.implement, workflows.human-digest, and an optional skill_prompts.<skill-name> per skill. If the file is missing the skill stops and asks; it never creates it.
• The GO rule. Nothing in the config opens the go-gate. git push, gh pr merge, gh release create and every reply, comment, approval, close or status change need your literal GO for that exact action. Scheduled or unattended runs are read-only.

Vendored from BuilderIO/skills (MIT) with AOS safety changes, see THIRD_PARTY_NOTICES.md; upstream docs: https://github.com/BuilderIO/skills/blob/main/docs/factory/README.md.

Details: docs/factory.md.

A2A: sessions that talk to each other

Live Claude Code, OpenCode, agy and Codex sessions exchange messages on localhost. Each live session runs a small sidecar bound to 127.0.0.1 on a random port with a per-session bearer token and registers in a local registry. There is no central service.

%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#FFFFFF", "primaryBorderColor": "#15171A", "primaryTextColor": "#15171A", "textColor": "#15171A", "actorBkg": "#E6F4EA", "actorBorder": "#1A7F3C", "actorTextColor": "#15171A", "actorLineColor": "#6e7681", "signalColor": "#6e7681", "signalTextColor": "#6e7681", "noteBkgColor": "#F7F4EC", "noteBorderColor": "#B9B5AA", "noteTextColor": "#15171A", "lineColor": "#6e7681", "sequenceNumberColor": "#15171A", "labelBoxBkgColor": "#F7F4EC", "labelBoxBorderColor": "#B9B5AA", "labelTextColor": "#15171A", "loopTextColor": "#15171A"}}}%%
sequenceDiagram
    participant C as Claude Code session
    participant R as local registry
    participant O as OpenCode session
    C->>R: aos-a2a list
    R-->>C: live peers (name, harness, url)
    C->>O: aos-a2a send --to opencode-1 "review this diff"
    Note over O: plugin injects it<br/>as a prompt,<br/>marked "never a GO"
    O-->>C: aos-a2a reply taskId "answer"
    Note over C: Codex: queue or resume<br/>agy: pull via inbox MCP

_{A2A message flow. A Claude Code session lists live peers in the local registry, sends a message to an OpenCode session and gets the reply back.}

aos-a2a list                              # live peers
aos-a2a send --to <name> "<text>"         # message a session
aos-a2a reply <taskId> "<answer>"         # answer an incoming message
aos-a2a watch <name> [--once]             # follow a peer read-only

Inbound per harness: Claude Code drains the inbox in a hook, OpenCode gets a plugin injection, Codex gets codex queue or codex exec resume, agy pulls through an inbox MCP (a running interactive agy session cannot be pushed into). For other channels use mcsc (one-shot task) or aos-acp (worker that may need a GO): docs/delegation-routing.md. Details: docs/a2a.md. In progress: intercom and a2abook on top of A2A.

For any MCP-capable harness. bin/aos-a2a-mcp.mjs is one stdio server that puts send and pull in the same place, so agy, Cursor and anything else that speaks MCP can join without a harness plugin. Tools: a2a_list, a2a_send, a2a_status, a2a_card, a2a_inbox_pull, a2a_reply. Three rules make it safe to expose to a model:

• It requires AOS_A2A_NAME. Send, reply and pull fail with AOS_A2A_NAME is not set instead of inventing an identity. a2a_reply has no name argument at all, so a model cannot write another session's reply.
• Text is data. Arguments are validated locally to 8 KiB before any network call, the MCP exposes no GO, approval or token argument, and peer text is always wrapped with the never-GO line. bin/a2a-inbox-mcp.mjs stays the separate pull-only inbox MCP already registered for agy.
• No secrets in output. Peer bearer tokens never appear in any tool result; they are read from the registry's separate token file over loopback.

Tools

_{Tool landscape. The universal harness on top, with the AOS tools and optional modules below it.}

AOS Hub and the sandbox

Hub tabs. Services, Catalog, Store and Plans. The Catalog tab is strictly read-only: it reads skills/, agents/, commands/, mcp_config.json, mcp_picks.json and the gateway allow list, and cross-checks the command list against plugin.json. No request value ever reaches the filesystem and nothing is written. The same CLI works without a browser: aos services status [--json], aos services start <id>, aos services stop <id> --confirm <id>, aos restart <id> --confirm <id>. Details: docs/hub.md.

Worker sandbox. aos-acp --sandbox <provider> wraps one worker launch, and only that launch. It is off by default and the provider is checked before anything starts:

An unknown provider, or one unavailable on this platform, fails with the reason and nothing is launched. --sandbox does not narrow paths itself: with --allow-default=scoped the path narrowing is agy's sandbox and the aos-go-gate hook, not this flag.

Fleet band and token-weather

Token-weather. The fleet mod turns the context percent of a session into a weather word with advice and a sparkline: for example ok at low use, compact soon around 80 percent, compact or start a new session above 90. The same band lists your Claude sessions, which work, which wait for you, and how many GO requests each has pending. Source: plugins/bdb-aos-fleet.

MCP servers

mcp_config.json defines 21 local stdio servers, built or warmed by the installer from mcps/. They reach your harnesses in one of two ways:

• Direct. Each server is written into every harness's MCP configuration, so every harness sees the same tool set. This is what you get with --without=gateway, --profile=minimal or after aos-gateway direct.
• Through the MCP gateway (the default). Every harness gets one aos entry pointing at 127.0.0.1:7790; behind it, 1mcp runs the servers on the gateway allow list once for all harnesses. aos-gateway adopt moves your own local servers behind it too, and aos-gateway direct switches back. deja, memB, mcsc and the OS-control servers always stay direct.

One residual worth knowing. The gateway entry carries its local token inline as an X-AOS-Token header in each harness config: the secret launcher (bin/aos-mcp-env.mjs) covers stdio servers, and a streamable-HTTP entry needs the header itself. The token stops browsers, not other local processes.

The column "Routing" says which path a server takes when the gateway is on; "Reaches the app via" says how it talks to its application. API keys and tokens live in ~/.aos/secrets.env (mode 0600), never inline in a harness config: docs/mcp-secrets.md.

Routing. The allow list in lib/gateway/config.js decides: the nine servers marked gateway are shared through the one aos entry once you enable it; everything else stays direct in every harness.

MCP gateway and one MCP per app

One MCP per app. For Blender, Resolume and After Effects the installer keeps a single candidate (mcp_picks.json): Blender official when Blender >= 5.1 is found, Resolume official when the Arena binary is found, the bundled server otherwise. The After Effects server is a pinned npx package and needs Node >= 24 (the legacy server only with AOS_AE_MCP=legacy).

Gateway (the default profile). aos-gateway runs a token-checking forwarder on 127.0.0.1:7790 in front of @1mcp/agent and shares an allow list of shipped servers behind one aos entry per harness. aos-gateway adopt moves your own local stdio servers behind it (skipping remote entries and entries with inline secrets). aos-gateway direct reverses everything. The token stops browsers, not other local processes. deja, memb_mcp and mcsc stay direct. Opt out with --without=gateway or --profile=minimal.

Skipped shapes. The gateway only writes into a harness whose config shape it has verified. Claude Desktop, Cline, Aider, VS Code, Windsurf, the Cursor app-support copy and a second agy candidate are reported as skipped: shape unverified and are never modified, because no vendor documentation for their remote-entry shape is recorded. The verified rows are Claude Code, Cursor (~/.cursor/mcp.json), Roo Code, OpenCode, Codex (config.toml) and Antigravity.

%%{init: {"theme": "base", "themeVariables": {"lineColor": "#6e7681", "edgeLabelBackground": "#f6f1e8", "textColor": "#15171A", "clusterBkg": "#F7F4EC", "clusterBorder": "#B9B5AA", "titleColor": "#15171A", "primaryColor": "#FFFFFF", "primaryBorderColor": "#15171A", "primaryTextColor": "#15171A"}}}%%
flowchart LR
    subgraph D["Direct (gateway off)"]
        direction LR
        H1("Claude") --> S1[("github")] & S2[("blender")] & S3[("resolume")]
        H2("OpenCode") --> S1 & S2 & S3
        H3("Codex") --> S1 & S2 & S3
        H4("agy") --> S1 & S2 & S3
    end
    subgraph G["Gateway (default)"]
        direction LR
        G1("Claude") & G2("OpenCode") & G3("Codex") & G4("agy") --> F("aos entry<br/>127.0.0.1:7790<br/>token check")
        F --> M("1mcp agent<br/>127.0.0.1:7791") --> U1[("github")] & U2[("blender")] & U3[("resolume")]
        G1 -.->|"stays direct"| X[("memb_mcp, deja, mcsc")]
    end
    D ~~~ G

    classDef plan fill:#E6F4EA,stroke:#1A7F3C,color:#15171A
    classDef build fill:#FFFFFF,stroke:#15171A,color:#15171A
    classDef gate fill:#1A7F3C,stroke:#1A7F3C,color:#FFFFFF
    classDef human fill:#F7F4EC,stroke:#5B6168,color:#15171A
    classDef store fill:#F7F4EC,stroke:#B9B5AA,color:#15171A
    linkStyle default stroke:#6e7681,stroke-width:2px

    class H1,H2,H3,H4,G1,G2,G3,G4 plan
    class S1,S2,S3,U1,U2,U3,X store
    class F,M gate
    style D fill:#F7F4EC,stroke:#B9B5AA,color:#15171A
    style G fill:#F7F4EC,stroke:#B9B5AA,color:#15171A

_{Direct and gateway routing. With the gateway on (the default) every harness shares one aos entry in front of the 1mcp agent; with it off each harness talks to each server directly.}

Reference. docs/mcp-gateway.md.

Plugins and marketplace

Plugin manifest. .claude-plugin/plugin.json + marketplace.json (generated by npm run plugin:build). AOS ships plugin manifests for Claude Code (.claude-plugin/), Codex (.codex-plugin/) and Antigravity (plugin.json); OpenCode has no marketplace concept and loads a local plugin instead. Sources: docs/marketplaces.md.

The Claude marketplace bdb-marketplace offers four plugins: bdb-aos (skills and subagents), bdb-aos-fleet, bdb-aos-sessions and bdb-aos-alert. When Claude Code is found, the installer offers the three mods (-y enables them) and registers them in ~/.claude/settings.json itself; --without=fleet,sessions,alert or --profile=minimal skips them, and Uninstall removes them. The npm installer still performs each harness's plugin registration best-effort; the CLI commands above are the manual equivalents. The marketplace route carries skills and subagents only — the npm installer is the recommended route because it also sets up gate hooks and MCP servers.

Skills discovery. Every harness finds skills in its native directory (~/.claude/skills, ~/.agents/skills, ~/.codex/skills, ~/.roo/skills, etc.). To browse and install additional skills after install:

npx skills add hybridlabor-api/aos

This discovers all 270 curated skills and installs them into the universal ~/.agents/skills directory (used by all harnesses and the AOS CLI).

AOS CLI

A lightweight CLI harness built on pi, a coding agent that runs in the terminal. AOS CLI reads ~/.agents/skills (written by the installer) and ~/.agents/AGENTS.md (the dispatcher graph as system instructions), runs no MCP servers of its own, and needs Node >= 22.19 (pi's floor, higher than the main AOS installer).

aos-cli "what is the fastest way to fix this bug"
aos-cli --continue                    # resume the previous session

The CLI launcher (packages/aos-cli/bin/aos-cli.mjs) ships with an AOS-themed dark mode (aos.json), the ten core skills from core-skills.json (ask-tim, aos-setup, systematic-debugging, archify, etc.), and two in-session read-only commands (/aos shows the install menu; /aos-status runs the health check).

Install it through the AOS installer with the AOS CLI target: npx -y @hybridlabor-api/aos@latest -y --platforms=10. The package is private and is not published on npm, so npm i -g @hybridlabor-api/aos-cli does not work.

Memory and knowledge

Installed as optional modules by the installer; aos doctor verifies them and the AOS Hub Services tab shows them.

• memB (@hybridlabor-api/memb): local, offline vector memory with an MCP server (add_memory, search_memory, list_memories, delete_memory), a WebUI on port 8088, and an ambient hook that injects relevant memories into Claude Code sessions. Skills: memb-skill, memb-ingest, bdb-memb-mcp.
• deja (@vshulcz/deja-vu, installed with memB): indexes your agent transcripts locally with secrets redacted; deja fix on an error, deja wip when resuming, deja search for past sessions. Skill: deja-memory.
• OpenWiki (openwiki CLI): generates and refreshes a grounded wiki of a codebase, with a visualizer on port 4321 and a background daemon. Skill: openwiki-skill; this repo's own wiki is under .openwiki/.
• Synapse (@hybridlabor-api/bdb-synapse): renders a repository as a 3D code city and replays agent sessions through it. Skill: synapse-integration-skill.

aos-setup brings a machine to a verified state for all four; aos-project-init binds one project to them (slug, wiki, memory, AGENTS.md).

What's included

The subagents (45)

Roster. 45 agents are compiled into the native agent format of Claude Code, Antigravity, Codex and OpenCode; Cursor, Windsurf, Roo and Aider get none and use the rules in AGENTS.md instead. Sources are in agents/. AOS pins no model: agents inherit the session model unless .aos/pipeline.json overrides a role per harness (docs/agent-models.md).

What the seven pipeline nodes do. Architect turns the goal into a system plan after reading the existing architecture. TechLead turns the plan into a capability map (module boundaries, dependency direction, build order) before any build node starts, and rejects back to Architect if it does not hold. godmode-ui-ux leads the frontend, godmode-engineering the backend, godmode-media-eventtech the creative and show-control work. Reviewer is an adversarial correctness review of build-node output against the plan's contract; Shipping runs the mechanical gate (lint, typecheck, tests, a11y, seo) and enforces the GO gate. The auxiliary 22 are not nodes of the graph. Subagents never inherit a GO and never invoke each other.

Skills by category

Categories. 270 curated skills, discoverable by every harness (the full generated catalog is in the next section). Eight categories, enforced by npm run validate:

• bdb-core: Core AOS infrastructure, pipelines, tools, and utilities: startcycle, startcycle-graph, startcycle-graph-user, agenttrail, plan-canvas, aos-a2a, aos-gateway, aos-store, master-session, codebase-memory, and more.
• design-ui-ux: Frontend, UI design, accessibility, tokens, motion, anti-slop: senior-frontend, ui-ux-pro-max, tailwind-patterns, shadcn, wcag-audit-patterns, and more.
• engineering-method: Architecture, testing, debugging, CI/CD, code quality: software-architecture, test-driven-development, systematic-debugging, ci-pipeline, github-actions-generator, docker-expert, makefile-pro, and more.
• library: Language and framework specifics: TypeScript, Node.js, Python, React, Postgres, Prisma, Next.js, Drizzle ORM, Go, and more.
• media-eventtech: 3D, video, show control, spatial design: godmode-eventtech, threejs-skills, the creative-software MCP skills, and more.
• engineering-hardware: PCB and electrical design: godmode-hardware-pcb.
• saas-ops: Running a SaaS end to end: golive, pb-deploy-saas, pb-health-weekly.
• business-ops: The commercial office side: pb-offer, pb-invoice-check.

Browse everything

Generated catalog. Built from the repo files (frontmatter of every SKILL.md, agents/, commands/). Open a section to see names and one-line descriptions.

Skills

Persona layer. The Godmode skills are specialized personas that directly map to the build and ship nodes of the dispatcher graph.

All UI/UX work — the godmode-ui-ux persona and the design skills it routes through, such as bdbdesignpro — draws components first from the pinned BDB component and motion-icon library (@bdb shadcn registry backed by npm @hybridlabor-api/ui-motion-library), before falling back to third-party registries or building from scratch.

Entry points and navigation.

• ask-tim: Skill recommendation by description
• bdbrainstorm and bdbmediastorm: Multi-agent ideation sessions ending in an executable plan
• teamwork-preview: Prompt crafting, role delegation, collaboration setup
• Grilling family: grill-me (general audit), grill-with-docs (documentation-grounded), triage (prioritization)
• CI/CD and generators: ci-pipeline, github-actions-generator, docker-expert, makefile-pro
• Code quality: bdb-security-audit, systematic-debugging, silent-failure-hunter, bdbresilience
• Framework specialists: Full coverage of TypeScript, React, Next.js, Drizzle ORM, Prisma, Python, Go, and more

Skills CLI. The library is also readable by the skills CLI:

npx skills add hybridlabor-api/aos

Playbooks

35 pb-* playbooks turn recurring jobs into guided runs with declared GO points. See Playbooks for how a run works and the full table by domain.

Optional modules

Optional by design. The installer's module picker offers these and Quick Update keeps them current. AOS works standalone without any of them. Pick them non-interactively with -y --modules=<id>,<id> or AOS_MODULES; the ids are the names below plus rustauri, styleseed and codebase-memory. Anything vendored ships inside the kernel, so those install with no download.

memB: local vector memory

@hybridlabor-api/memb: offline, local vector memory with an MCP server

…