agents you orchestrate

ayo

Build agents from plain files. Compile to standalone binaries.
Discover, invoke, and compose them from your terminal.

$ brew install ayo-ooo/tap/ayo

or  clone & build from source

What is ayo

Your agents are binaries.
Not services.

ayo is an agent compiler and orchestrator. Define an AI agent in a few plain files, compile it into a standalone binary, then register it so any tool on your system — including your coding agent — can discover and invoke it.

No Docker. No API server. No runtime dependencies. Just binaries that talk to each other through stdin and stdout, the way Unix intended.

Every agent gets a beautiful terminal UI, multi-provider LLM support, and a sandboxed shell — out of the box.

~/agents
$ ayo fresh code-reviewer
✔ Created code-reviewer/
 
$ ayo runthat . --register
compiling code-reviewer...
✔ Built ./code-reviewer
✔ Registered in ayo registry
 
$ ayo list
code-reviewer  v1.0.0  tool
summarizer    v2.1.0  conversational
 
$ ayo run code-reviewer '{"path":"src/"}'

The thesis

Three ideas. One tool.

01

Agents are artifacts

An agent isn't a web app. It's a compiled binary. You build it, ship it, run it anywhere. No containers, no orchestration layer, no uptime monitoring. Just a file that does a job.

02

Compose like Unix

Every ayo agent reads stdin and writes stdout. Pipe them together. ayo run extract | ayo run summarize | ayo run translate — each agent does one thing well.

03

Your tools build tools

Coding agents like Claude Code can use ayo to build, register, and invoke purpose-built sub-agents — transparently, as code, not as a black box.

How it works

Define. Compile. Register. Run.

Four steps. Plain files become orchestrated agents.

📝

ayo fresh

Scaffold a new agent. Edit config.toml and system.md to define its behavior.

⚙️

ayo runthat

Compile into a standalone Go binary. Static linking, zero deps, cross-platform.

📋

--register

Add it to the ayo registry. Now any tool on the system can discover it.

⚡

ayo run

Invoke by name. Pipe between agents. Your coding agent can call it too.

Orchestrate

Discover, invoke, compose.

Every ayo agent is self-describing. The registry makes them discoverable. Standard I/O makes them composable.

discovery
$ ayo list --json
[
  {
    "name": "reviewer",
    "type": "tool",
    "version": "1.0.0"
  },
  {
    "name": "summarizer",
    "type": "conversational"
  }
]
 
$ ayo describe reviewer --json
// returns input_schema, output_schema,
// skills, hooks, invocation examples
composition
$ ayo run extractor '{"file":"data.csv"}' \
  | ayo run summarizer \
  | ayo run translator '{"lang":"es"}'
 
# Each agent does one thing well.
# Piped together, they're a pipeline.
 
$ ayo run reviewer '{"path":"src/"}' \
  --non-interactive -o review.json
 
✔ Output written to review.json

Coding agent integration

Your coding agent builds agents for you.

Claude Code, Cursor, or any coding agent can use ayo to create purpose-built sub-agents, register them, and invoke them later — all transparently, as code.

Claude Code + ayo
you: I need an agent that reviews Go code for
     security issues and outputs structured JSON.
 
claude: I'll create that with ayo.
 
  $ ayo fresh security-reviewer
  // writes config.toml, system.md,
  // input.jsonschema, output.jsonschema
  $ ayo runthat . --register
  ✔ Built ./security-reviewer
  ✔ Registered in ayo registry
 
claude: Done. The agent is compiled and registered.
       I can invoke it anytime with:
       ayo run security-reviewer '{"path":"src/"}'
 
you: Run it on the auth module.
 
  $ ayo run security-reviewer \
    '{"path":"src/auth/","language":"go"}' \
    --non-interactive
 
claude: Found 2 critical issues in token validation...

Agent types

Two modes from one format.

Add an input schema and it's a tool. Leave it out and it's conversational. Same files, different behavior.

Tool Agent

Schema → Forms → One-shot

Has an input.jsonschema. Gets TUI forms, CLI flags, JSON input, and piped stdin. Processes input and returns a result.

  • JSON Schema → interactive TUI forms
  • Structured input and output
  • CLI flags auto-generated from schema
  • One-shot execution, perfect for pipelines
? Language      Go
? Path          src/auth/
? Strict mode   Yes
✔ Reviewing code...
Conversational Agent

Chat → Sessions → Memory

No input schema. Gets a rich chat TUI, session persistence, and streaming responses. For open-ended tasks.

  • Rich Bubbletea chat interface
  • Session persistence with --session
  • Interactive mode with --chat
  • Streaming responses
■ researcher session: abc123

you: What are the security implications
     of the new auth flow?

agent: Let me examine the implementation.
       Checking token validation...

The agent format

Plain files. That's the whole agent.

A few files define everything — personality, capabilities, I/O shape. No SDKs, no boilerplate, no framework lock-in.

config.toml required 
# Agent metadata
[agent]
name = "code-reviewer"
version = "1.0.0"
description = "Reviews code for bugs"

# Model configuration
[model]
default = "claude-sonnet-4-6"

[defaults]
temperature = 0.3
max_tokens = 4096
system.md required 
# Code Reviewer

You are a senior code reviewer.

## Behavior

- Review for bugs, security
  issues, and style violations
- Be constructive and specific
- Suggest concrete improvements
- Use the shell to read files

## Output Format

Group by severity:
critical > warning > suggestion
input.jsonschema optional — makes it a tool agent 
{
  "type": "object",
  "properties": {
    "language": {
      "type": "string",
      "enum": ["go", "python", "typescript", "rust"],
      "description": "Language to review"       // → select dropdown in TUI
    },
    "path": {
      "type": "string",
      "description": "Path to review"           // → text input + CLI flag
    },
    "strict": {
      "type": "boolean",
      "description": "Enable strict mode"       // → confirm toggle
    }
  }
}

Features

Everything an agent needs. Nothing it doesn't.

📋

Agent Registry

Register agents. Discover by name. List, describe, and invoke from anywhere on the system.

🔁

Self-Describing

Every agent embeds its own metadata. Tools can introspect schemas, skills, and capabilities via --ayo-describe.

🤖

Multi-Provider LLM

Anthropic, OpenAI, OpenRouter, Groq, Gemini, and more. First-run model picker built in.

🛡️

Sandboxed Shell

Pure-Go POSIX shell with command blocking. The one tool every agent gets.

🎨

Beautiful Forms

JSON Schema becomes interactive Huh forms automatically. Select, text, numeric, confirm.

💾

Sessions

Resume conversations with --session. Interactive --chat mode. Context that persists.

📚

Skills & Hooks

Embed capability docs as skills. Run lifecycle hooks on agent events. Extend without code.

📦

Zero-Dep Binaries

Static Go binaries. Homebrew, curl install, or just copy the file. Runs anywhere.

🎨

Cross-Platform

Build for macOS, Linux, and Windows with a single flag. --platform all does the rest.

Quick start

From zero to orchestrated agent in 90 seconds.

1

Install ayo

$ brew install ayo-ooo/tap/ayo
2

Scaffold an agent

$ ayo fresh my-agent

Creates config.toml and system.md. Edit them to shape your agent.

3

Compile and register

$ ayo runthat . --register

Compiles to a standalone binary and adds it to the registry in one step.

4

Run it

$ ayo run my-agent

Invoke by name from anywhere. Pipe it. Let your coding agent call it. It's just a binary.