Skip to content
/
Tier B A6 Multi-agent orchestrator

Yao

yao · YaoApp/yao · ★ 7.5k · last commit 2026-05-26

Primitive shape 3 total
Hooks 2 MCP tools 1
00

Summary

Yao — Summary

Yao is an open-source Go runtime (7.5k stars) for building AI agents and full-stack web applications as a single self-contained binary — no Python, Node.js, or containers required on the host. The binary bundles a V8 JavaScript engine, a REST API layer, a component-based web UI engine (SUI), a built-in chat UI (CUI), MCP client support (process/SSE/stdio transport), vector search, a knowledge graph, and GraphRAG. Agents are defined by attaching TypeScript Create and Next lifecycle hooks to any of three executor modes: LLM (OpenAI/Anthropic/etc.), CLI Agent (runs Claude Code, OpenCode, or Codex in an isolated sandbox container with VNC desktop), or Pure Hook (deterministic TypeScript logic, no AI). The CLI Agent mode is unique: it containerizes Claude Code itself and exposes it as an agent backed by a Skills Ecosystem — SKILL.md packs dropped into any CLI Agent directory are auto-discovered. The Memory API has four scopes (request, session, user, team). Multi-agent delegation calls other Yao agents or runs parallel fan-out. Compared to the seeds, Yao is closest to agent-os (both provide a runtime + scaffold for agent execution), but Yao is dramatically more capable: it ships a full-stack web runtime, a built-in V8 TypeScript engine, container sandboxing for CLI agents, and GraphRAG — none of which appear in any seed.

01

Overview

Yao — Overview

Origin

YaoApp organization, Go-based, licensed under a custom "NOASSERTION" license (not standard OSI). Long history as a "low-code" Go runtime before pivoting to the AI agent space. The yaoagents.com website positions it as "App Runtime for the AI Era."

Philosophy

From the README:

"Think of Yao Agent as a cage, not an animal. What you put inside determines the behavior; the cage keeps it controlled."

"Create Hook runs before the executor — inject context, enforce constraints, route requests. Next Hook runs after — validate output, trigger downstream actions, drive multi-step loops. The AI does the heavy lifting. You define the boundaries."

The Hook-based philosophy: every request flows through a deterministic Create → Executor → Next pipeline. The hooks are TypeScript functions run by the embedded V8 engine; they enforce the "cage" (boundaries) while the LLM or CLI agent provides the intelligence.

Three executor modes

Mode Executor Use case
LLM OpenAI, Anthropic, Gemini, etc. Conversational AI, Q&A, content generation
CLI Agent Claude Code, OpenCode, Codex in a container Computer use, sandbox isolation, SKILL ecosystem
Pure Hook TypeScript code only (no AI) Deterministic logic, routing, menu flows

All three share the same Create/Next hook interface. This means you can mix AI and non-AI steps in the same agent pipeline.

"Yao" etymology

From the README:

"Yao (爻, yáo) is the fundamental symbol in the I Ching — the building block of the eight trigrams. Like a binary digit, it has two states. Their combinations describe the patterns of everything."

Key product: Yao Desktop

Desktop application (yaoagents.com/download) that wraps the Yao binary in a GUI. Ships separately from the CLI runtime.

02

Architecture

Yao — Architecture

Distribution

  • Type: standalone-repo (Go binary; download from releases or build from source)
  • Binary name: yao
  • Platforms: ARM64 + x64 (macOS, Linux, Windows)
  • Required runtime: None on host (Go runtime embedded; V8 engine bundled)
  • License: NOASSERTION (custom, non-standard)

Repository structure (selected)

yao/
  agent/          # Agent runtime types
    llm/          # LLM provider adapters
    memory/       # Memory API (4 scopes)
    robot/        # CLI agent (container runner)
    sandbox/      # Container isolation
    store/        # Memory storage
    search/       # Vector + graph search
  mcp/            # MCP server implementation
  mcpclient/      # MCP client
  cmd/            # CLI entry point
  runtime/        # Core runtime
  script/         # V8 JavaScript engine integration
  sui/            # SUI web UI engine
  cui/            # CUI (chat UI) engine
  kb/             # Knowledge base (GraphRAG)
  llmprovider/    # LLM provider factory
  connector/      # External connectors
  store/          # Key-value + vector stores
  sandbox/        # Container sandbox
  flow/           # Flow engine
  model/          # Data model (DB-backed)
  api/            # REST API layer
  query/          # Query engine

Key architectural choices

  1. Single Go binary: no external dependencies; yao runs on bare metal
  2. Embedded V8: TypeScript hooks execute in-process via embedded V8 engine (no Node.js)
  3. Container sandboxing: CLI Agent mode runs coding agents (Claude Code, etc.) in Docker containers with optional VNC desktop
  4. MCP as client and server: mcp/ serves tools; mcpclient/ connects to external MCP servers
  5. Skills ecosystem: SKILL.md files dropped into CLI Agent directories are auto-discovered

Memory API (4 scopes)

Scope Description
Request Single request lifetime
Session Conversation session
User Per-user, cross-session
Team Shared across team members

Build

make build   # produces ./yao binary
03

Components

Yao — Components

Core runtime components

Component Type Purpose
Create Hook TypeScript function Pre-executor: inject context, route, enforce constraints
Next Hook TypeScript function Post-executor: validate output, trigger downstream, loop control
LLM Executor Go module Calls OpenAI/Anthropic/etc. with accumulated messages
CLI Agent Executor Go module Runs Claude Code/OpenCode/Codex in Docker container with VNC
Pure Hook Executor Go module Runs only TypeScript hooks (no AI call)
Memory API Go + storage 4-scope persistent memory (request/session/user/team)
MCP Server (mcp/) Go module Expose Yao tools as MCP server
MCP Client (mcpclient/) Go module Connect to external MCP servers (process/SSE/stdio)
SUI Engine Go + TypeScript Component-based web UI (server-side rendering)
CUI Engine Go + TypeScript Built-in chat UI for agents
Knowledge Base (kb/) Go GraphRAG: vector search + knowledge graph + hybrid search
Data Model (model/) Go JSON/YAML-defined DB tables + relations
REST API (api/) Go Route mapping to model queries or TypeScript processors
Skills Ecosystem SKILL.md files Drop-in capability packs auto-discovered by CLI Agent

LLM providers (via llmprovider/)

OpenAI, Anthropic, Google Gemini, + any OpenAI-compatible API.

Search capabilities

  • Vector search (OpenAI embeddings or FastEmbed)
  • Knowledge graph (entity-relationship retrieval)
  • GraphRAG (hybrid vector + graph)

Multi-agent delegation

  • Delegate to specialist Yao agents (agent-to-agent calls)
  • Parallel fan-out: call multiple agents simultaneously

SKILL.md ecosystem

SKILL.md files (Markdown files describing agent capabilities) dropped into a CLI Agent's directory are automatically discovered. This is the same SKILL.md format used across the ecosystem.

Yao Desktop

Desktop application wrapping the Yao binary (separate download).

05

Prompts

Yao — Prompts

Verbatim: README agent design metaphor

Think of Yao Agent as a **cage, not an animal**. What you put inside determines 
the behavior; the cage keeps it controlled.

`Create Hook` runs before the executor — inject context, enforce constraints, 
route requests.  
`Next Hook` runs after — validate output, trigger downstream actions, 
drive multi-step loops.  
**The AI does the heavy lifting. You define the boundaries.**

Technique: Metaphor-driven design philosophy ("cage, not animal") that shapes how developers think about prompt injection. The hook system makes system prompt construction explicit TypeScript code rather than a static string.

Verbatim: Three modes summary

| Mode | Executor | When to use |
|------|----------|-------------|
| **LLM** | OpenAI, Anthropic, etc. | Conversational assistants, Q&A, content generation |
| **CLI Agent** | OpenCode, Claude Code, Codex in a container | Computer use, sandbox isolation, SKILL ecosystem |
| **Pure Hook** | Your own TypeScript code | Deterministic logic, routing, menu flows — no AI needed |

All three share the same Hook interface. You can mix them freely — route some 
requests through the LLM, handle others with pure code, all inside a single 
`Create Hook`.

Technique: Decision table as system architecture doc. Developers "choose" the executor at configuration time; the hook interface is invariant. This is a pattern where the prompt framework is the configuration artifact.

SKILL.md pattern

Yao adopts the SKILL.md format (same as the claude-plugin ecosystem) for CLI Agent capability packs. Skills describe what the CLI Agent can do and are injected as context into the agent's system prompt automatically.

09

Uniqueness

Yao — Uniqueness

Differs from seeds

No seed is truly close to Yao's architecture. The nearest is agent-os (both are "runtime environments for agents" rather than Claude Code augmentations), but Yao is vastly more capable: it ships a Go binary with an embedded V8 engine, container isolation for CLI agents, a full-stack web UI engine (SUI), a chat UI (CUI), GraphRAG, and 4-scope memory — none of which appear in agent-os. The CLI Agent mode is unique in the entire catalog: Yao containerizes Claude Code itself and wraps it as an agent executor, treating Claude Code as a capability to be orchestrated rather than as the orchestrator. This inversion — Yao runs Claude Code inside Docker while exposing control hooks above it — has no equivalent in any seed or peer.

Positioning

Yao is the only framework in this batch that is a compiled Go binary with an embedded JavaScript runtime. It targets organizations that want a self-contained, zero-dependency agent runtime that bundles both AI and full-stack web capabilities in one executable. The "no Node.js, no Python required" positioning is unique.

Distinctive features

  1. Single Go binary: zero external runtime dependencies — the rarest distribution model in this catalog
  2. CLI Agent mode: containerizes Claude Code / OpenCode / Codex as agent executors with VNC desktop support — unique architecture
  3. Embedded V8: TypeScript hooks run in-process without Node.js
  4. 4-scope memory API: request / session / user / team — explicit multi-tenancy built into memory
  5. GraphRAG: vector + knowledge graph + hybrid search in one integrated module
  6. SKILL.md auto-discovery: skills dropped into CLI Agent directories are automatically discovered

Observable failure modes

  1. License ambiguity: "NOASSERTION" license is not standard OSI; commercial use may have restrictions
  2. Container dependency for CLI Agent: Docker required for the most powerful mode; not "zero-dependency" in that case
  3. No Python/TS SDK: library usage requires the Go binary; embedding in Python/Node apps is indirect
  4. Documentation: primarily at yaoagents.com/docs (external); GitHub README is sparse on API details
  5. No community debugging tools: no equivalent of LangSmith or VoltOps for trace inspection
04

Workflow

Yao — Workflow

LLM agent request flow

Request → Create Hook (TypeScript) → LLM Executor → Next Hook (TypeScript) → Response
Phase Artifact
1. Incoming request HTTP request or chat message
2. Create Hook fires Context injected, constraints applied, routing decided
3. LLM call Model response with tool calls
4. Next Hook fires Output validated, downstream actions triggered, loop controlled
5. Response Final output to user

CLI Agent flow (Claude Code in container)

Phase Artifact
1. Create Hook prepares context Agent instructions + SKILL.md content
2. Container launched Docker container with VNC desktop
3. Claude Code / OpenCode runs Produces code, files, or actions
4. Next Hook validates Output checked, loop decision made
5. Result returned Files, diffs, or execution output

Multi-step loop (Next Hook driven)

The Next Hook controls looping:

// Next Hook returns:
// { status: "continue" } → loop back to executor
// { status: "done" } → return final result
// { status: "error", message: "..." } → error path

Multi-agent delegation

// Create Hook delegates to specialist
const result = await agent.call("specialist-agent-name", message);
// Or parallel:
const results = await Promise.all([
  agent.call("agent-a", task1),
  agent.call("agent-b", task2),
]);

Approval gates

None built-in. Pure Hook executor can implement arbitrary approval logic in TypeScript.

Configuration

Agents defined as YAML/JSON configuration files specifying executor type, hook paths, and model settings.

06

Memory Context

Yao — Memory & Context

Memory API (4 scopes)

Scope Lifetime Use case
Request Single request/turn Tool call results, transient state
Session Conversation session Ongoing dialogue context
User Per-user, persistent User preferences, learned patterns
Team Shared across team Organization-wide shared knowledge

The Memory API is accessible from TypeScript hooks:

// In a Create Hook
const userHistory = await memory.get("user", userId, "preferences");
await memory.set("session", sessionId, "context", enrichedContext);

Storage backends

Built on Yao's store/ module which supports:

  • Key-value store (for memory scopes)
  • Vector store (for knowledge base / RAG)

Knowledge base (GraphRAG)

The kb/ module provides:

  • Vector search: OpenAI embeddings or FastEmbed
  • Knowledge graph: entity-relationship retrieval
  • GraphRAG: hybrid vector + graph queries

Cross-session handoff

Yes — User and Team memory scopes persist across sessions by design.

Context injection

The Create Hook is responsible for injecting context into the LLM call. Developers write explicit TypeScript to assemble the context from memory, knowledge base, MCP resources, and incoming message.

State files

Stored in the configured backend (varies by deployment). No fixed file paths; the store/ module abstracts the backend.

07

Orchestration

Yao — Orchestration

Multi-agent

Yes. Two patterns:

  1. Delegation: Create Hook calls a specialist Yao agent and uses its result
  2. Parallel fan-out: Create Hook calls multiple agents simultaneously

Orchestration pattern

hierarchical (delegation) and parallel-fan-out (simultaneous calls).

Max concurrent agents

Unknown (limited by Go goroutines and container availability; no hard cap in framework).

Isolation mechanism

Container — CLI Agent mode runs coding agents (Claude Code, OpenCode, Codex) in Docker containers with optional VNC desktop. This is the most explicit container-based isolation in this batch.

LLM and Pure Hook modes: no isolation (run in-process).

Multi-model

Yes. llmprovider/ factory supports OpenAI, Anthropic, Google Gemini, and any OpenAI-compatible API. Agents can specify different providers. No predefined role mapping; hooks implement routing logic.

Execution mode

event-driven — Yao runs as a persistent HTTP server; requests trigger the Create→Execute→Next pipeline.

Crash recovery

Unknown. As a Go binary with persistent server, it does not inherently crash-recover from mid-run failures.

Context compaction

Not explicitly documented. Session memory is developer-managed via the Memory API.

Consensus

None.

Prompt chaining

Yes — Next Hook can return { status: "continue" } to loop back to the executor, forming explicit chains. The accumulated message history grows with each iteration.

MCP

Yao can both serve tools as an MCP server (mcp/) and connect to external MCP servers as a client (mcpclient/), supporting process, SSE, and stdio transports.

Streaming

Unknown — the README shows a chat UI (CUI); streaming support not explicitly documented.

08

Ui Cli Surface

Yao — UI & CLI Surface

CLI binary

yao — the main Go binary; covers all runtime modes.

Installation:

  • Download from GitHub Releases
  • Build from source: make build
  • Yao Desktop (GUI wrapper)

Built-in web UI

SUI Engine: Component-based web UI with server-side rendering. Yao serves web pages directly from the binary — no separate frontend server needed.

CUI (Chat UI): Built-in conversation interface for agents. Accessible at a configured URL when Yao runs in agent mode.

Yao Desktop

A desktop application wrapping the Yao binary, available at yaoagents.com/download. Provides a GUI for running and managing Yao agents without the CLI.

Mission Control

The README shows a "Mission Control" dashboard screenshot (docs/mission-control.png) — a web UI for monitoring and managing agents.

IDE integration

None found in the public repository. No CLAUDE.md, AGENTS.md, or .claude/ directory.

MCP server mode

Yao agents can expose their capabilities as MCP servers (via mcp/ module), making them consumable from Claude Code, Cursor, and other MCP clients.

VNC Desktop (CLI Agent mode)

When running a CLI Agent (Claude Code in container), Yao optionally provides a VNC desktop, enabling visual monitoring of the agent's GUI operations.

Observability

trace/ module in the repository. OpenTelemetry integration not explicitly confirmed in the README.

Related frameworks

same archetype · same primary tool · same memory type

Claude-Flow / Ruflo ★ 55k
A6 Multi-agent orchestrator

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

Hermes Agent (NousResearch) ★ 168k
A6 Multi-agent orchestrator

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

OpenCode ★ 165k
A6 Multi-agent orchestrator

Terminal-first AI coding agent with multi-model routing, native desktop app, and a typed .opencode/ configuration system for…

OpenHands ★ 75k
A6 Multi-agent orchestrator

Open-source AI software development platform (open-source Devin alternative) with Docker sandbox isolation, 77.6% SWE-bench…

DeerFlow ★ 70k
A6 Multi-agent orchestrator

Long-horizon superagent that researches, codes, and creates by orchestrating parallel sub-agents with isolated contexts in Docker…

oh-my-openagent (omo) ★ 60k
A6 Multi-agent orchestrator

Multi-provider AI agent orchestration for OpenCode: escape vendor lock-in by routing Sisyphus (Claude/Kimi/GLM) and Hephaestus…