Getting started

Install

curl -fsSL https://uze.sh/i | sh

Every release until v1 is an alpha. Each one ships six tarballs (four Linux, two macOS), a CycloneDX SBOM, SHASUMS256.txt and signed provenance you can check with gh attestation verify <file> --repo hiukky/uze.

A uze the install script placed keeps itself current: the workspace checks for a new release when it opens and every hour after, installs it, and says so in the sidebar — restart uze to run it, and click the notice to read what changed. uze upgrade does the same on demand, and says why when it cannot replace the binary it is running from.

Provision your harnesses

uze setup detects every harness uze supports and provisions any that are missing through each vendor's own official installer — never a mirror, never a repackaged binary (ADR-010).

$ uze setup
▸ Provisioning 4 harness(es) through official routes…
✓ [1/4] claude-code: ready (update; version 2.1.260)
  ↳ shim: ~/.uze/shims/claude
✓ [2/4] codex: ready (update; version 0.152.1)
  ↳ shim: ~/.uze/shims/codex
✓ [3/4] opencode: ready (update; version v0.0.0-beta-18999)
  ↳ shim: ~/.uze/shims/opencode
✓ [4/4] antigravity: ready (install; version 1.1.26)
  ↳ shim: ~/.uze/shims/agy

✓ Setup completed — all 4 harness(es) ready.

The word in parentheses is what setup did: install where the binary was absent, update where it was already there. Installer output is buffered per harness ($UZE_HOME/state/logs/setup-<harness>.log; --verbose streams it). Each ↳ shim line is the runtime PATH shim for that harness — the thing that also brings an agent back to its conversation after a reboot.

A harness that could not be provisioned is a failure, not a warning: setup exits non-zero and names it, so an image build never reads "all ready" over a missing binary. It is idempotent, and reading state changes nothing:

$ uze setup list                 # detected harnesses and their setup state
$ uze setup inspect claude       # one harness, in full

Names accept the stable id (claude-code), an alias (claude, agy), or the label (Claude Code).

The first time you run uze on a machine it asks the same question before anything else, with the harnesses it found already checked, then opens the workspace once setup is done. Calling it off still opens the workspace; the new-agent menu offers only harnesses that are set up, and sends you to Integrations when there are none.

Add a plugin

A plugin always comes from a marketplace — a Git repository holding a marketplace.json, whether you spell it as a URL or as a clone on this machine. uze-official is embedded in the binary and needs no registration.

$ uze market add you/marketplace                      # github; or gitlab:you/marketplace, a URL, ./a-local-clone
$ uze market list
$ uze flow@my-marketplace                             # add it to this project

The <plugin>@<market> shorthand is project scope: it declares the plugin in agents.yaml and records what it resolved to in agents.lock. To install into the machine Store without touching any project, use uze plugin install flow@my-marketplace. Neither implies the other.

$ uze plugin inspect flow    # capabilities, and how each harness will receive them

Share one project context

AGENTS.md at the project root is the portable baseline, and you never run a command to maintain it: uze install leaves it composed and every harness bridge in step, and uze status says which file the context comes from and whether each detected harness reads it.

$ uze install    # resolve, install, and leave the context reconciled
$ uze status     # which file, which harnesses, and anything still owed

Only the delimited regions uze owns are ever written. Anything you wrote around them is preserved, and a vendor file holding its own content is reported rather than overwritten. The region-by-region detail is on the agent surface — uze agent context inspect | plan | reconcile — written for an agent maintaining the file, not for you. See Project context.

Check the health

$ uze doctor     # store, harness detection, attachment health, receipt ledger
$ uze status     # how this project's environment and context reach each harness

doctor is a report, not a chore list: it repairs the deterministic, uze-owned artifacts it can prove are safe to rebuild, and escalates only what genuinely needs your decision.

When something needs explaining rather than repairing, the workspace and the terminal server keep a journal without being asked — ~/.uze/cache/logs/, rolled daily and pruned to a week. Nothing to turn on after the fact.

Run agents side by side

Running uze with no arguments opens the workspace — a persistent terminal that hosts your agent sessions:

$ uze

Agents start where the project says — beside you in the space's own root, or each in an isolated checkout of its own, so two of them never touch each other's files or yours. Ctrl+G shows what one changed, Alt+A the project's own diagrams, and Ctrl+O switches to management — Overview, Plugins, Extensions, Integrations, Profiles — and back.

A fresh clone

agents.yaml and agents.lock are committed with the project, so a new machine reconstructs the same environment from the pair alone — at the same commits, with each package's bytes verified against the recorded digest before anything is installed:

$ git clone …
$ uze install

What happens next

• Concepts — the model behind the loop.
• Creating a plugin — the canonical layout, and how to publish one.
• Harnesses — what each harness gets, natively.
• CLI reference — every command.