Beta·every release is a pre-releaseAPIs and harness behavior are still changing·every release until v1 is a pre-release
uzev1 beta
Reference

agents.yaml

The file a project writes, the file uze derives from it, and what each one is allowed to say

Two files at the project root, both committed, with one rule between them:

FileWritten byHolds
agents.yamlyouWhat the project declares: which marketplaces it draws from, which plugins it wants, and, under workspace:, how its agents work
agents.lockuzeWhat resolving those declarations produced: the commit each marketplace was read at, and a digest of the bytes that landed

The lock carries no intent, so deleting it loses nothing: uze install regenerates it. Deleting agents.yaml loses the project's decisions.

git clone && uze install reconstructs the environment from the pair alone.

agents.yaml

Two kinds of key, one per module. The package manager's sit at the root; the workspace's live under one workspace: section, which a project that only installs plugins never writes:

marketplaces:
  ai:
    git: https://github.com/you/plugins
    ref: main
    plugins:
      - review
      - changelog

workspace:
  worktree: always
  delivery: push

Created by uze install or uze add <plugin>@<market>, explicit acts of setting a project up, with the package manager's vocabulary written out and commented. Nothing about the workspace is written, not even commented: the section appears when you choose something in the workspace or write it yourself. Nothing that merely reads a project creates the file.

Every key is optional; a project declaring only a workspace policy is as valid as one declaring only plugins. Unknown keys are an error, not silence: a typo in a file a person wrote should not be read as a decision, and neither is a key written twice. Writing revision: or integrity: here is refused by name: those belong to the lock. So is a version:, at the root or on a plugin: the file has no schema version, and a plugin is pinned by its marketplace's ref:. A plugin may be declared under one marketplace only.

This document is patched in place, so a comment you wrote beside an unrelated entry survives uze <plugin>@<market>.

marketplaces

Every marketplace the project draws from, keyed by the name you refer to it by, with what it takes from each. Exactly one source per marketplace:

marketplaces:
  ours:
    git: https://github.com/acme/plugins
    ref: main               # optional: branch, tag or sha; also the pin that moves
    subdirectory: market    # optional
    plugins: [review, changelog]
  local:
    path: ../marketplace
    plugins: [bench-runner]

Plugins are bare names: the source above says where they come from, and ref: is what moves them.

A marketplace is a Git repository, whether you spell it as a URL or as a directory on this machine. Not because Git is how the bytes travel (a directory does that), but because a commit is the only thing that answers are these the bytes I installed? and is there something newer? A path: is therefore where this machine reads the repository; what the lock records is its remote and a commit, which is what another machine can reproduce.

The lock records every Git source in one spelling: git@github.com:acme/plugins.git, ssh://git@github.com/acme/plugins and https://github.com/acme/plugins.git all become https://github.com/acme/plugins. That is a name, not a transport: each machine reaches it anonymously when it is public, and with its own credential helper or SSH key when it is private, so nothing in these files says how to authenticate, and a collaborator with no key installs a public marketplace as easily as you do. A marketplace you develop is read from your checkout with uze market link, which touches neither file.

The official marketplace, uze, is built into the binary, so a project lists what it takes from it with no source:

marketplaces:
  uze:
    plugins:
      - workspace

A git: or path: on that name is refused: the binary is its only source. The uze plugin itself is never listed, since every project has it already.

workspace

How uze workspace runs the agents it launches, and where the project keeps the artifacts that describe it. One flat section. Where a worktree lives, .worktrees/<id>, is fixed and deliberately not declared here. Its branch starts as agent/<id> and takes the name the agent gives its work, judged by branch.

The section is the workspace's. The package manager carries it without reading it, so a mistake in it never fails uze install or uze status; the workspace reports it.

KeyDefaultMeaning
worktreemanualWhen an agent launched here gets a worktree: always, at launch, or manual, only when you move it with To worktree. Until then it works in the primary checkout, on your branch
deliverynoneWhere finished work is put: merge (fast-forward the local target) or push (push the task's branch to the remote). Both rebase onto the target and run the gate first. Undeclared, there is no delivery
targetthe branch the primary checkout is on when the task is createdThe branch finished work targets
branchconventionalThe vocabulary an agent's own name for its work is judged against: a preset (conventional, gitflow, flat, agent) or your own list of types. flat takes a subject with no type; agent names no work and keeps the generated agent/<id>
linknoneIgnored files a fresh worktree links from the primary checkout, like .env
setupnonePrepares a worktree, run in it after linking every time an agent takes it, once you approve it. Where a cache that records its own path is repaired after a checkout changes hands. A failure warns; it never blocks a launch
gatenoneRun in the task's worktree on the rebased commits, once you approve it. A non-zero exit refuses delivery
slotspeak concurrencyThe most worktrees that may exist at once
idle_days3Days a free worktree may sit unused, since an agent last left it, before it is removed, its branch kept. Until then it is reused, so a project keeps as many worktrees as it had agents at once
actionsnoneWhat the agent is asked at each state its work reaches; see below
artifactsnoneWhere the project keeps what describes it; see below

Every key but branch, actions and artifacts is about a worktree, so none of them does anything for an agent working in the primary checkout until it is moved into one. branch still judges such an agent's name, which sets its label and never your branch.

setup and gate each take one command or a list run in order. Use the list when a failure should say which step failed:

workspace:
  worktree: always
  delivery: push
  target: main
  branch: conventional
  link: [.env, .env.local]
  setup: pnpm install
  gate:
    - pnpm test
    - pnpm lint
  slots: 3
  idle_days: 3
  artifacts: docs

A command is one line, and it runs the same on Linux, macOS and Windows. uze runs it in a small shell of its own, so nothing depends on which shell the machine has. That shell reads what a setup or gate line usually needs:

  • &&, || and ;, pipes, and <, > and >>
  • NAME=value command, $NAME, $(command), globs and ~
  • cat, cd, cp, echo, exit, export, head, mkdir, mv, pwd, rm, set, sleep, test, unset and xargs, built in, so cp .env.example .env works on a Windows machine with no cp
workspace:
  setup: test -f .env || cp .env.example .env
  gate:
    - pnpm test
    - mkdir -p reports && pnpm lint > reports/lint.txt

Some lines need more than that shell reads: if, for or while, functions, ${NAME}, [, or a flag its built-in commands do not have, like head -1. Such a line still runs, in sh, on Linux and macOS, exactly as before. It does not run on Windows, and uze status says which part kept it there. To run it on Windows too, write it once for each shell. Windows runs the windows line in Windows PowerShell:

workspace:
  setup:
    posix: for f in *.example; do cp "$f" "${f%.example}"; done
    windows: Get-ChildItem *.example | % { Copy-Item $_ ($_.Name -replace '\.example$') }

posix: alone also runs a line in sh when you want sh itself.

A step with no line for the machine it runs on is not run there. A setup step is skipped with a warning naming it; a gate step refuses the delivery, because work nothing checked never lands. uze status lists every such step.

Approving the commands

setup and gate are shell lines from the repository, and they run with your permissions. So uze runs none of them until you have read the exact lines and said yes, once per project on each machine. Until then a worktree is placed without its setup, and nothing is delivered. The workspace asks with a Review button when it opens the project, and uze workspace allow asks from a terminal:

uze workspace allow     # show this project's setup and gate lines, and approve them
uze workspace revoke    # withdraw the approval; nothing runs until it is given again

The approval names those exact lines. Change one, add one or remove one, and the workspace asks again before anything runs. An agent cannot approve its own project's commands: uze workspace allow refuses inside an agent uze launched, and needs a person at a terminal to answer. uze status says when a project's commands are waiting for you.

A link entry must be relative, stay inside the repository, and be ignored by it: a tracked file linked into a worktree would land in the agent's commits as a symlink. All three are checked when the file is read, not silently dropped. The agent writes through a link into your primary checkout, so only what it reads belongs there.

The policy lives here rather than in machine state because it is the project's decision, shared by everyone who clones it. Placement reads the primary checkout's file: a worktree's own agents.yaml is its agent's work, and applies once delivered.

actions

What the agent is asked when its work reaches a state: one line of text per state, sent into the agent's pane as if you had typed it. The workspace opens no pull request and fixes no check itself. It rebases, runs the gate and puts the work where delivery says, and everything after that is the agent's, asked in the project's own words.

workspace:
  delivery: push
  actions:
    on_change: Commit your work with the git:commit skill, then end your turn.
    on_publish: Open a pull request for this branch against main with the git:pr skill, then end your turn.
    on_conflict: The rebase onto main is paused here. Resolve it preserving your change, run git rebase --continue and the checks, then end your turn.
    on_fail: The project's checks failed after the rebase. Fix them on this branch, commit, and end your turn.
KeyThe work isSent on its own when
on_changechanged in the checkout, not committednever
on_publishon the remote, with no request yeta push delivery pushed it
on_conflictpaused mid-rebasea rebase uze ran stopped on conflicts
on_failrefused by the gatethe gate failed on a delivery

Clicking the status in the workspace's tab strip sends that state's line too, so on_change, which is never sent on its own, is one click away: with it declared, an uncommitted status appears beside the change count. Nothing is sent while the agent is working or while you have text typed in its input: the click says why, and nothing is queued. Any other state is only shown.

on_conflict and on_fail have a line of uze's own when the project declares none, since in both the agent's checkout is waiting on the agent: a rebase paused, a branch the gate refused. Declaring them replaces those lines.

To ask for a skill, say so in the line, as you would in the prompt: Use the git:pr skill to open a pull request. An unknown key, or a value that is not a line of text, is reported and left out, and the rest still works.

artifacts

Where the project keeps the artifacts that describe it: one directory, or a list of them, each read as deep as it goes.

workspace:
  artifacts: docs
  # or several:
  # artifacts: [docs, design]

It names places, never kinds. What a file is, it says by its own content, and each surface takes the files it recognizes and ignores the rest: the architect surface draws the Mermaid files it finds there, and the spec surface lists the decision records. A kind of artifact uze learns later needs no new key.

An entry that climbs out of the project (../) or starts at the machine's root refuses the whole declaration, naming the entry, because this file is checked in and would point somewhere else on every machine.

Nothing lists the files. Each one says what it is in its own first word, which is also the area it appears under, and names itself with Mermaid's own front matter, falling back to its file name:

---
title: System context
---
C4Context
  Person(dev, "Developer")
  System(uze, "uze")
  Rel(dev, uze, "Installs, launches, reviews")
The diagram starts withArea
C4Context, C4Container, C4Component, …C4
sequenceDiagramSequence
flowchart, graphFlowchart

Levels, and the way down to the code

C4 is a model of levels (a system, the containers inside it, the components inside one of those), and the files are joined into levels the same way they are sorted into areas: by what they already say. An alias names one element in every view, and a view's outermost boundary says which box it is the inside of: a container view's System_Boundary is the inside of the System with its alias, a component view's Container_Boundary the inside of the Container with its alias:

system-context.mmd    System(uze, "uze", …)
containers.mmd        System_Boundary(uze, "uze") { … Container(cli, "uze CLI", …) … }
core-components.mmd   Container_Boundary(cli, "uze CLI") { … }

Several component views of one container sit side by side, each one level below it. Where an alias cannot say it, an element's $link to another of the files names its inside instead.

A box like that is marked, and entering it opens the file that draws its inside; the way in is kept as a trail, every step of which goes back. The last level is the code itself. Mermaid's own $link on an element names where it lives, relative to the project, and entering that box opens it in the code surface:

Component(store, "store", "Rust module", "Owns installed bytes", $link="crates/core/src/store.rs")

A flowchart says the same with click store href "crates/core/src/store.rs".

Within an area the files are listed by name, except C4, which is listed the way it is read: the context, then containers, then components, then the dynamic and deployment views.

A .mmd or .mermaid file of any other kind is still listed, under Other, with the reason it was not drawn: a file that silently fails to appear looks like a lost file.

Everything here is a file somebody wrote. What the project is (where its lines are and which of them are hot) is measured rather than written, and is the code surface's map: press m beside the file tree, or its Map chip.

agents.lock

Generated, never edited, and deleted outright when nothing is left to reproduce. It is spelled the way agents.yaml spells things, so a reader moving between the two files does not learn the same vocabulary twice:

version: 1
marketplaces:
  ai:
    git: https://github.com/you/ai
    ref: main
    revision: 02d2c9831eb619821c574622a78bbc5f6189485a
plugins:
  git:
    marketplace: ai
    integrity: sha256:f429f157f7cec03d702f1749416ea59174b9af79c94fc281756467b0cb6b81cd

Resolution adds two things to a declaration (and, for the official marketplace, the uze version, below):

  • revision: the immutable commit the marketplace was read at. Non-optional beside git, so "a marketplace with no pin" cannot be written down. Reproduction reads this, never the declared ref:: a lock that re-resolved main would install whatever had been pushed since.
  • integrity: SHA-256 over the bytes the Store ingested, verified on install before ingest and before any harness sees anything. A mismatch names both digests and installs nothing. A path: marketplace records none: a digest of a directory somebody is editing would be wrong by the next command, and a pin that is routinely wrong teaches people to ignore pins.

The official marketplace has no repository and no commit, so it has no entry under marketplaces:. The lock records the uze version that resolved its plugins instead, at the top (uze: 1.0.0), and each of them with its integrity as above. Those plugins follow the binary that runs: when the machine's bytes or the lock's are another uze build's, uze install replaces them with this one's, rewrites the lock and reports them as updated, never as a mismatch.

Everything else in the file was already in the manifest, and is repeated only so the lock stands alone on a machine that has never read one. version stays at 1 while uze is pre-release; the number exists to tell apart shapes a released uze wrote.

Staleness is decidable offline

Comparing the two files answers whether the lock still stands: no network, no re-resolution, so uze status works in a tunnel. A declaration is stale when the lock never resolved it, resolved it from a different marketplace, or the marketplace it comes from is declared differently now. A lock entry the manifest no longer declares is not staleness, it is a removal.

A floor, not a ceiling

A machine runs one revision of each plugin, shared by every project and every agent on it, and keeps it at the newest. The lock does not say what runs; it says what a machine starts from:

  • A machine without the plugin installs exactly the locked revision. This is the fresh clone, the teammate, the CI runner.
  • A machine behind the lock is raised to it by uze install. A teammate moved the pin and you pulled it.
  • A machine past the lock keeps what it has. uze install never downgrades and never moves a pin, and uze status shows the plugin as installed at a revision other than the lock's. That is the ordinary state after an update, not a fault; uze update in the project records it.

What these files are not

They are project scope. Neither records what is installed on your machine: that lives in the Store under ~/.uze, and uze add -m never writes here. The two are independent by design; see Machine and project.

On this page