uio-ai 0.2.0

Provider-agnostic AI agent/skill/prompt runner

uio

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.

Why uio?

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.

Concepts

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.

Documentation

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.

Quickstart

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 cost

Definitions 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.

License

GNU Affero General Public License v3.0