uio is the agent runtime for CI/CD. Define agents, skills, and prompts as plain markdown files with YAML frontmatter — checked into your repo, executed headlessly in pipelines, and wired to any LLM provider. The origin story covers how and why.
uio occupies a distinct niche: definition-as-code automation. The agents, skills, and prompts you author live in your repo, run headlessly in CI/CD, carry distinct GitHub App identities, and produce auditable cost records.
Interactive assistants (chat UIs, IDE plugins, terminal REPLs) are what you open when you want to build something at a terminal. uio is what runs at 3am when no one is watching.
| Need | Interactive assistant (e.g. Copilot, Cursor) | uio |
|---|---|---|
| Designed for headless CI/CD execution | No | Yes |
| Definitions stored in git | No | Yes — plain markdown files |
| Reproducible across environments | No | Yes — provider-agnostic |
| Scriptable / composable | Limited | Yes — uio agent run, uio skill run |
| Auditable cost records | No | Yes — JSONL ledger, uio cost |
| Multi-agent GitHub identities | No | Yes — planner / coder / reviewer App identities |
| Definition sharing | No | Yes — git-hosted registries |
| Auditable history of changes | No | Yes — git blame, PR diffs |
If your use case is "trigger an agent on push, review its output in a PR" — that is exactly what uio is designed for. See docs/20-positioning.md for the full comparison and rationale.
| Concept | What it is |
|---|---|
| Agent | A multi-turn tool-use loop that can execute shell commands and call MCP tools; defined in *.agent.md |
| Skill | A focused, composable subtask — same loop as an agent, but user-directed via uio skill run; defined in *.skill.md |
| Prompt | A single-shot LLM instruction with no tool loop; defined in *.prompt.md |
| Workflow | A sequential pipeline of agent/skill/prompt steps with output chaining; defined in *.workflow.md |
| Tool | An external capability the model invokes mid-loop (MCP tools, run_command) — agent-directed, not user-directed |
See the Glossary for precise definitions of all terms, including the skill vs tool distinction.
Full documentation lives in docs/ — covering installation, core concepts, a quickstart, CLI reference, configuration, providers, MCP integration, the chat REPL, cost ledger, registry, writing definitions, etc.
See Use Cases for end-to-end worked examples.
pip install uio-ai
# Scaffold .uio/ and install bundled examples
uio init --examples
# Run one of the bundled examples
uio skill run summarise "Your text here"
uio agent run repo-health
# Inspect the full system prompt before running
uio explain agent repo-health
# Interactive streaming chat
uio chat
# View token spend
uio costDefinitions live in .uio/:
my-project/
└── .uio/
├── agents/ my-agent.agent.md
├── skills/ my-skill.skill.md
├── prompts/ my-prompt.prompt.md
├── workflows/ my-workflow.workflow.md
└── memory/
See Writing Definitions for the full file format and authoring guide.