ayo is a command-line tool for running AI agents that can execute tasks, use tools, and chain together via Unix pipes. Define agents with custom system prompts, extend them with skills, and compose them into powerful workflows.
go install github.com/alexcabrera/ayo/cmd/ayo@latestThat's it. Built-in agents and skills install automatically on first run.
Start chatting with built-in default agent:
ayo @ayoShortcut to prompt @ayo single prompt:
ayo "write a haiku about terminal emulators"Attach files for context:
ayo -a go.sum "review this code"Agents are AIs with custom system prompts and capabilities. Each agent is a directory containing configuration and instructions.
| Agent | Description |
|---|---|
@ayo |
The default agent - a versatile command-line assistant |
@ayo.research |
Web-enabled research agent for finding information online |
@ayo.skills |
Skill management agent for creating and organizing skills |
# Interactive chat (continues until Ctrl+C)
ayo @ayo.research
# Single prompt
ayo @ayo.research "what's new in Go 1.22?"ayo agents create @myagentThis launches an interactive wizard to configure your agent. For non-interactive creation:
ayo agents create @helper -n \
--description "A helpful assistant" \
--model gpt-4.1 \
--system "You are concise and friendly."@myagent/
├── config.json # Agent configuration
├── system.md # System prompt
├── skills/ # Agent-specific skills
├── input.jsonschema # Optional: structured input schema
└── output.jsonschema # Optional: structured output schema
ayo agents list # List all agents
ayo agents show @ayo # Show agent details
ayo agents update # Update built-in agentsSkills extend agent capabilities with domain-specific instructions. They follow the agentskills spec.
| Skill | Description |
|---|---|
ayo |
CLI documentation for programmatic use |
debugging |
Systematic debugging techniques |
web-search |
Web search capabilities |
# Create in current directory (project-local)
ayo skills create my-skill
# Create in user shared directory
ayo skills create my-skill --shared
# Create in dev location (./.config/ayo/skills/)
ayo skills create my-skill --devEach skill is a directory with a SKILL.md file:
my-skill/
├── SKILL.md # Required: skill definition with YAML frontmatter
├── scripts/ # Optional: executable code
├── references/ # Optional: additional documentation
└── assets/ # Optional: templates, data files
The SKILL.md format:
---
name: my-skill
description: What this skill does and when to use it.
metadata:
author: your-name
version: "1.0"
---
# Skill Instructions
Detailed instructions for the agent...ayo skills list # List all skills
ayo skills list --source=built-in # Filter by source
ayo skills show debugging # Show skill details
ayo skills validate ./my-skill # Validate a skill directory
ayo skills update # Update built-in skillsAgents with structured I/O schemas can be composed via Unix pipes. The output of one agent becomes the input to the next.
# Chain agents together
ayo @code-reviewer '{"files":["main.go"]}' | ayo @issue-reporterWhen stdout is piped:
- UI (spinners, reasoning, tool calls) goes to stderr
- Raw JSON output goes to stdout for downstream consumption
# List chainable agents
ayo chain ls
# Inspect schemas
ayo chain inspect @myagent
# Find compatible agents
ayo chain from @source-agent # What can receive this output?
ayo chain to @target-agent # What can feed this input?
# Validate and test
ayo chain validate @myagent '{"key": "value"}'
ayo chain example @myagent # Generate example inputLocated at ~/.config/ayo/ayo.json:
{
"$schema": "./ayo-schema.json",
"default_model": "gpt-4.1",
"provider": {
"name": "openai"
}
}| Variable | Description |
|---|---|
OPENAI_API_KEY |
OpenAI API key |
ANTHROPIC_API_KEY |
Anthropic API key |
OPENROUTER_API_KEY |
OpenRouter API key |
GOOGLE_API_KEY |
Google AI API key |
ayo uses XDG-style directories:
| Platform | User Config | Built-in Data |
|---|---|---|
| macOS/Linux | ~/.config/ayo/ |
~/.local/share/ayo/ |
| Windows | %LOCALAPPDATA%\ayo\ |
%LOCALAPPDATA%\ayo\ |
~/.config/ayo/ # User configuration
├── ayo.json # Main config
├── agents/ # User agents
├── skills/ # User skills
└── prompts/ # Custom system prompts
├── prefix.md # Prepended to all agents
└── suffix.md # Appended to all agents
~/.local/share/ayo/ # Built-in data
├── agents/ # Built-in agents
├── skills/ # Built-in skills
└── .builtin-version # Version marker
Resources are discovered in this order (first found wins):
- Agent-specific (in agent's
skills/directory) - Project-local (
./.config/ayo/) - User config (
~/.config/ayo/) - Built-in (
~/.local/share/ayo/)
This allows project-specific overrides of user and built-in resources.
ayo [command] [@agent] [prompt] [--flags]| Flag | Short | Description |
|---|---|---|
--attachment |
-a |
File attachments (repeatable) |
--config |
Path to config file | |
--debug |
Show raw tool payloads | |
--help |
-h |
Help |
--version |
-v |
Version |
ayo agents list # List agents
ayo agents show <handle> # Show details
ayo agents create <handle> # Create agent
ayo agents update # Update built-insayo skills list # List skills
ayo skills show <name> # Show details
ayo skills create <name> # Create skill
ayo skills validate <path> # Validate skill
ayo skills update # Update built-insayo chain ls # List chainable agents
ayo chain inspect <agent> # Show schemas
ayo chain from <agent> # Find output consumers
ayo chain to <agent> # Find input producers
ayo chain validate <agent> # Validate input JSON
ayo chain example <agent> # Generate example inputayo setup # Reinstall built-ins
ayo setup --force # Overwrite without promptingAgents execute tasks through tools. The default tool is bash, which executes shell commands.
When the agent runs a command, you'll see:
- A spinner with the command description
- The command output in a styled box
- Success/failure status with elapsed time
Tools are configured per-agent in config.json:
{
"allowed_tools": ["bash"]
}In interactive mode, ayo maintains conversation context across turns:
- First
Ctrl+Cinterrupts the current request - Second
Ctrl+Cat the prompt exits the session
ayo @ayo # Start interactive sessionayo is designed for Unix pipelines:
# Pipe input
echo "explain this" | ayo
# Pipe output (UI goes to stderr)
ayo @reporter "analyze logs" | jq .
# Chain agents
ayo @analyzer '{"data":"..."}' | ayo @reporterWhen stdin or stdout is a pipe, ayo adjusts its behavior:
- UI output always goes to stderr
- Raw content goes to stdout
- JSON output is not markdown-rendered