<!-- Source: https://console.uubright.com/docs/manager/ -->
# Your Manager and its workers

Each workspace has one **Manager**: the agent you talk to there. You tell it what
you want, approve its plan, and it starts **workers** for the parts of the job and
reports back. The app pins the Manager at the top of the workspace, with its
workers under it.

The Manager answers quick questions, discussion and simple web lookups itself. It
hands implementation and longer research to an existing worker in that area or
a new worker, then ends its turn so you can keep talking while they work. A
message sent while the Manager is still in a foreground turn waits in its queue;
you can edit or withdraw it until that turn finishes. Worker reports can start
another Manager turn, so it should not hold a turn open just to watch progress.

## Words in the app

The app uses plain words for what you do. The [HTTP API](https://console.uubright.com/docs/api/) and some
older pages still use the internal names. They mean the same thing:

| In the app | In the API and older pages | Meaning |
|---|---|---|
| Workspace | workspace | A context, such as one product or client, with its own agents, repositories, logins and deliverables. |
| Manager | the workspace's `managerTaskId`; usually a [lead](https://console.uubright.com/docs/lead/) task | The one agent you talk to in a workspace. It plans, starts workers and reports. |
| Workers | tasks with `createdBy` or `parentTaskId` set to the Manager, its PR reviewers, and members of its own room | Agents the Manager started, shown under it. |
| Tasks | sessions | Tasks you started yourself. |
| Team log | the Manager's [room](https://console.uubright.com/docs/rooms/) | How the Manager and its workers coordinate, as a tab in the Manager's task. |
| Shared (preview) | other rooms | Rooms outside a Manager, such as Codex on your laptop. Off the main navigation. |
| Deliverables | artifacts (formerly Outputs, the Library) | Results to review, each Draft, Needs review, Approved or Published. See [Deliverable states](https://console.uubright.com/docs/artifacts/#deliverable-states). |
| Needs you, Board | inbox, board | Unchanged. |

## The sidebar

```
SciMigo ⌄                  🔍  ＋
● Needs you              3
★ Manager              3 workers · 1 needs you
   ├ Connector worker  ●
   └ Deploy the preview ●
Pinned
Tasks
```

- The top row is the workspace switch, then **Jump to a task** (🔍, also Cmd/Ctrl+K)
  and **New task** (＋). The switch's menu holds the other workspaces,
  **Workspace settings**, **Change Manager…** (when there is a Manager) and
  **Shared (preview)**; it opens even with one workspace.
- **Needs you** is one row with its count. It hides when nothing needs you and
  nothing waits under Updates; with only updates waiting it reads **Updates · N**.

- **★ Manager** is always first, set apart by an accent edge. Its second line
  counts active workers of all of them (**11 active of 26 workers**; a worker
  that finished but you haven't looked at yet counts as active) and everything
  waiting on you, the Manager included. It never moves, whatever its state.
- Its **workers** are nested under it in **Needs attention**, **Working** and
  finished history. Owner decisions come first, and each set is ordered by
  newest start. Workers with an
  open PR can show when review is in progress, what holds the PR, or when
  it is ready for your merge decision. A reviewer that stopped before filing
  a verdict says so on its row. History starts folded behind **Show finished
  workers**. Your choice is remembered for that Manager on this device.
  **▾** folds all workers away and remembers that fold too.
- On a phone, **Find a task** on the Tasks page narrows the list to tasks whose
  title, project or state contain every word you type, finished workers
  included. It's kept for the workspace on this device until **Show all**. Folding never hides anything from **Needs you** or the board:
  workers are counted there like any other task.
- **Pinned** and **Tasks** follow, as before. The Manager and its workers have
  no pin; they already have a fixed place.

On a phone, the **Tasks** tab lists the same way, Manager first. Choosing a
workspace in the switcher opens its Manager.

A worker is any task the Manager started:

- through its [lead tools](https://console.uubright.com/docs/lead/) (`task_create`), recorded as `createdBy`;
- through the HTTP API with `"parentTaskId": "<manager id>"`. A task knows its
  own id as `CCR_CLOUD_SESSION_ID`. The parent is for display only; it grants
  nothing;
- as a [local PR review](https://console.uubright.com/docs/lead/#local-pr-review) it asked for;
- by joining the Manager's own [room](https://console.uubright.com/docs/rooms/): one where the Manager is a lead
  and the only lead. A Manager that just joined another lead's room, or a shared
  room of peers, gets no workers from it;

and, the same way, anything such a worker started.

## The four steps

Working with a Manager goes in four steps:

1. **Describe**: say the outcome in your own words. A goal, not a task list.
2. **Approve the plan**: the plan comes back as a [decision](https://console.uubright.com/docs/tasks/#answer-decisions)
   card: who does what, and what you'll get.
3. **Watch**: workers appear under the Manager, and the board fills in.
4. **Review**: [deliverables](https://console.uubright.com/docs/artifacts/#deliverable-states) arrive to approve,
   merge or publish.

**Start your Manager**, and a Manager you haven't told anything yet, show these
four steps as cards with **Describe** lit. Once the Manager has a goal, a slim
strip at the top of its task shows which step it's on, worked out from what
happened, latest first:

| The strip shows | When |
|---|---|
| **Review** | A worker's (or the Manager's) newest deliverable needs review, or a PR of theirs is ready to merge. The note counts them. |
| **Watch** | Workers are running or waiting on you. The note counts them. |
| **Approve the plan** | The Manager has an open decision card ("Plan waiting for you"), or nothing has happened yet ("Planning"). |
| all four ticked | Its workers are done and nothing waits for review. The strip then hides by itself. |

**×** hides the strip on this device; **Show the four steps** in the Manager's
**⋯** menu brings it back, including once every step is done. On a phone the strip is
one line with the current step; **▾** shows all four. On a phone the steps move to the Manager tab's
overview instead, and the conversation doesn't repeat them.

## When a worker goes quiet

Each worker ends every turn by saying where it stands: done, ready with its PR,
waiting (on the Manager, you, a job, a review or something outside), or blocked.
You see it next to the worker's status at the top of its task.

The board has two rows above its columns when there is something in them:

- **Stalled** lists workers sitting idle with nothing set to wake them, and why.
  Such a worker is nudged automatically, once per reason and at most 3 times an
  hour; a worker still on the row after that needs a look. The row also lists tasks whose turn stalled, and the
  Manager when a worker has waited on it for over 10 minutes (the Manager is told
  too).
- **Review queue** lists the PRs workers reported ready, and for which Manager.
  The Manager gets each one once.

Tasks you started yourself are never nudged. Details are in
[Worker states and stalls](https://console.uubright.com/docs/lead/#worker-states-and-stalls).

## Team log

The Manager's task has two tabs. **Chat** is your conversation with it. **Team
log** is its [room](https://console.uubright.com/docs/rooms/): the briefs it sends workers, their reports, and the
questions and hand-offs waiting for you, at the top. The tab shows how many are
waiting. A Manager that isn't in a room has no team log; its lead actions show in
Chat. `#session=<id>&tab=log` links straight to the log.

## Start your Manager

A workspace without a Manager has a quiet **★ Start your Manager…** row in the
Manager's place. It opens the Start your Manager page, which also lists the
tasks you could make the Manager, each with a **Make this the Manager** button.
Opening the workspace from the switcher goes straight to the same page. Describe what you want and choose a project, if
any. A repository that isn't a project yet can be added right there under **Add a
project…**, from this server, by path or by clone URL, as in New task; it is then selected.
**＋ Add a project…** at the end of the **Project** list opens it too.
The app starts a lead task in **Auto** mode by default, with Claude Code or Codex as you choose; the form offers only the agents this computer has, and selects one of them. **Ask for approval** is available if you want the new Manager and its new workers to ask before actions outside their trusted set. The first time you start a Manager in Auto on a device, the form first says what Auto lets it do: the Manager and its Workers act without asking about each step, edit files and run commands in their checkouts, and can push branches and open pull requests with this computer's GitHub sign-in (`gh`). Choose **Start in Auto**, or **Use Ask for approval instead**. Workers start with their Manager's agent unless it asks for the other one. A paired phone can do
this too: it starts the lead with the default worker and budget limits, which only
the owner token can change. If the task starts but can't be made the Manager, the
app tries once more, then lists the new task first on this page so you can choose
**Make this the Manager**.

The same page lists recent tasks you started yourself. **Make this the Manager**
on one of them, or in any such task's **⋯** menu, makes it the Manager instead.
Workers and reviewers can't be the Manager. A task that isn't a lead can be the
Manager, but it can only start workers through the API with `parentTaskId`;
make it a lead with `PATCH /api/sessions/:id` and `{"lead": {}}` to give it the
[lead tools](https://console.uubright.com/docs/lead/).

## Change your Manager

A workspace has one Manager. Choose **Change Manager…** in the workspace menu,
the phone's top **⋯** menu, or the Manager task menu. Choose an agent and mode:

- **Continue this work** stops the current Manager, saves and pushes its branch when it has one, and starts a new conversation from a fresh handoff note. The note puts recent owner direction first, marks the original goal as historical, and includes recent progress, open requests, branch, PR and worker status. Later corrections take priority, so a long thread's first goal is not assumed to be current. The room handle and worker team carry over. This is how to switch between Claude Code and Codex or change Auto/Ask during a Manager task. The original task keeps its history and can be restored with **Undo** on the handoff card.
- **Start fresh** takes a new goal and project. The old Manager stops and becomes an ordinary task with its history; its existing workers remain separate tasks. The new Manager has no previous conversation or worker team.

Auto is selected for a new Manager even when the old Manager had no saved mode. Ask makes new workers ask too; workers already running keep their own modes. Changing the agent or mode starts a new task because the two CLIs do not share a conversation or support this mode change in place.

From the API, `PUT /api/workspaces/:id/manager` with `{"taskId": "s-…"}` sets
the Manager and `DELETE` clears it. Deleting the Manager's task clears it too.

On the server, set the Manager of an existing workspace with the CLI. For
example, to make an existing main thread the Default workspace's Manager:

```sh
npm run workspace -- set-manager default s-a4342cb2f019
npm run workspace -- set-manager default --clear
```

The CLI doesn't check the task; the app ignores a Manager it doesn't list.
