Overview
The terminal workspace where your agents run, in spaces, tabs and panes that survive closing it
The workspace is the half of uze that runs your agents. Run uze workspace
and you get one terminal that holds all of them, each in a tab, on a
branch and, if you want, in a checkout of its own.
It runs the agents you already have, set up by uze setup. It does not need
any plugin: whatever the package manager delivered is there
in every agent it starts.
uze workspaceWhat it does for an agent
- A worktree of its own, cut from your target branch, so agents never write over each other or over you. Where an agent works
- A name for its work, which becomes its branch. Its work gets a name
- Delivery: one click rebases it, runs your checks and merges it or pushes the branch. Bringing the work home
- Another harness, mid-task: the same agent carries on in Codex, OpenCode or any other one set up here, briefed on what happened. Continuing in another harness
- Nothing lost: unfinished work is kept on a shelf, and Recent lists every agent no pane carries, across every project. Work nobody finished
Spaces, tabs, panes
| What it is | |
|---|---|
| Space | A named group of agents, which can work in several projects. Alt+S adds one |
| Tab | A session inside it: an agent (Alt+N) or a shell (Ctrl+T) |
| Pane | The live terminal of the selected tab |
A new agent asks for the directory it works in, in a popup beside the space's
new, with its harness in a field that starts on the one you used last
(← → change it; Tab completes the directory). The directory starts on the project of the agent in front,
so another agent there is one Enter away. Rows mark the projects the space
already works in, with their branch, and the other Git repositories. A space can
hold agents of front, back and landing at once, and each agent's row
names its project.
A shell you open while an agent is selected belongs to that agent: it starts in the agent's checkout and closes with it. A shell of the space belongs to no project, wherever it goes.
Alt+O opens the overview of the agent in front: what
it was asked, the agents.yaml settings of the checkout it works in, and its
project's plugins, memory and worktrees.
The right end of the tab strip counts the selected checkout's changes
(+12 -3; click it to open the Review). For an agent in your
own checkout it also shows what a pull would bring (↓2) and a push would send
(↑1). Click the pull count to fast-forward.
Selecting text
The workspace owns the mouse, so it does the selecting your terminal would
otherwise do. Drag over text in a pane, a diff, a file, a spec or the agent
drawer, and releasing copies it to the clipboard. A drag past the edge scrolls
and keeps selecting, and a pane's selection reaches into its scrollback. The
copy travels as an OSC 52 escape, so your terminal has to allow it. In most
terminals, holding Shift while dragging skips uze and uses the terminal's
own selection instead.
Nothing is lost when you close it
Your agents keep running when you quit the workspace, and are exactly where you
left them the next time you run uze workspace. After a reboot, uze starts
each agent again in the checkout it was working in, back in the conversation it
was having.
When an agent finishes
An agent that finishes while you are looking elsewhere leaves a check on its tab. To hear it too:
uze config notification on # ring the terminal bell when an agent finishes
uze config notification silent # neverExtensions
An extension is something the workspace shows beside your agents. Four are built in, and a plugin can bring more.
The built-in ones follow the order you read a change in: what it intends, how the project is shaped, what the code now is, and what the branch changes. Each opens where the selected tab is and closes with the same key.
| Key | Shows | |
|---|---|---|
| Spec | Alt+X | The change the agent works from: proposal, design, tasks |
| Architect | Alt+A | The project's diagrams |
| Code | Alt+E | The checkout's files, a search over them and a map |
| Review | Alt+G | What the agent's branch changes, commented line by line and sent back to the agent |
A plugin can bring more, in the bar under the agent area, in the sidebar, in
a drawer beside the agent or in a band over its pane. The official
marketplace has three, in the workspace plugin: gsd, focus and
contributions. Extensions says how you
allow and turn off each one and what the official ones show, and
Writing an extension how to write your own.
Management
Ctrl+O, or the mark at the top right of the sidebar, opens management over
the workspace and closes it again: what every agent carries on this machine
and what it costs (Overview), your plugins and marketplaces
(Marketplace), each agent's setup (Integrations), Extensions,
Shortcuts, and appearance and notifications (Settings), all with the
mouse.