Welcome
What uze is and the problem it solves
Welcome
uze is the compatibility and distribution layer for agent tooling. You
install a plugin and write one AGENTS.md; uze keeps the bytes in one place and
delivers them to each harness — Claude Code,
Codex, OpenCode,
Antigravity — through the most native mechanism
that harness has. A real plugin where one exists, a native capability where it
doesn't, an adapter only as a last resort.
And it is where you run those agents. A terminal that can give each agent a
checkout of its own (.worktrees/<id>, on branch agent/<id>), watches what
each one did, and brings the work home to the target branch.
Status: alpha. APIs, schemas and harness integration behavior may change while the cross-harness model is being validated. Real-harness evidence lives in the Conformance Lab.
The problem
Coding agents each have their own plugin format, their own skills directory, their own way of reading project instructions. Maintaining the same skill or the same project context four times over is how agent setups rot.
And once you run more than one at a time, they collide: two agents editing one checkout, with your own uncommitted work in the middle.
What uze does
Everything below works today. The two scopes never touch each other's state:
machine commands read and write ~/.uze, project commands read and write the
directory you are in.
Distribution — machine scope
| Mechanism | What it gives you |
|---|---|
| Store | Owns a package's bytes and is the single source of truth. It never writes anything a harness reads, and no integration writes back into it. |
| Marketplaces | A marketplace is a Git repository, remote or cloned locally; uze-official is embedded in the binary. A plugin is always resolved through one, pinned to a commit and verified by digest before it is ingested. |
| Receipts | Every managed artifact — a symlink, a generated directory, a config entry, a bridge region — carries a typed receipt. Drift blocks a destructive change instead of authorizing it. |
| Trust | An MCP command or a hook handler is execution you are being asked to authorize. uze lists every one before installing, and refuses rather than assuming yes when it cannot ask. |
| Maintenance | uze doctor repairs the UZE-owned artifacts it can prove are safe to rebuild, and escalates only what needs your decision. |
Portability — what travels
| Capability | How it travels |
|---|---|
| Skills | The canonical capability. Its portable semantics are who may invoke it — the invoke: {model, user} block — translated into each vendor's own encoding. |
| MCP servers | Delivered through each harness's native mechanism, or folded into the plugin envelope where one exists. |
| Agents | Markdown agent profiles projected onto each harness's native agent surface — including a generated TOML file for Codex, which has no on-disk Markdown format. |
| Hooks | One authored hooks.json and a shell-command ABI, so a hook works everywhere without a per-vendor runtime. |
| Instructions | A package's own AGENTS.md is composed into the project's, one owned region per package. |
| Project context | AGENTS.md is the baseline; uze install keeps each harness's bridge in step, and uze status says whether they are. |
| Project environment | agents.yaml declares what the project wants; agents.lock records what resolving it produced. git clone && uze install rebuilds it. |
| Profiles | Autonomy, sandbox and model preferences translated into each harness's own settings, with the fidelity reported per axis. |
Orchestration — the terminal
| Mechanism | What it gives you |
|---|---|
| Terminal runtime | A local server owns the pseudoterminals, so a pane survives the client leaving. Close the TUI; the agent keeps working. |
| Workspace | Spaces, tabs and panes, with a prompt history you can jump back through. |
| Isolated checkouts | An agent can be placed in a reusable slot on a branch of its own, before its harness starts — every agent, where the project declares it. |
| Task lifecycle | Running, uncommitted, ready, conflicted, integrated, parked — read from Git, never announced by an agent. |
| Delivery | Rebase onto the target inside the agent's own checkout, run the project's gate, then hand off, merge, or open a pull request. |
| Extensions | Two surfaces built into the TUI: Code — a checkout's changes, files, history and a map of where its lines are — and Architect, the project's own Mermaid diagrams drawn in cells. |
| Themes | Every colour and mark uze draws is named by meaning, so one theme file restyles the CLI, the TUI and what a pane is told the terminal looks like. |
The guarantees around it
- Conformance Lab — the real harness binary against a synthetic world, in Docker, with zero internet and zero tokens. A harness that cannot meet part of a contract declares that with a reason; it never omits the check.
- One-way dependencies, enforced by tests — the domain, the orchestration layer and the CLI/TUI may not name a harness. A new harness is one integration vertical and one registry entry, with no change to Store, Engine or Router.
The loop
$ uze setup # detect + provision every harness through official routes
$ uze flow@my-marketplace # add a plugin from a marketplace to this project
$ uze status # context, environment and what is still owed
$ uze doctor # diagnostics: store, harnesses, attachment healthOn another machine, git clone && uze install reproduces the same environment
from the two committed files.
Or run uze with no arguments for the workspace — your agents, side by side.