<!-- Source: https://console.uubright.com/docs/workspaces/ -->
# Workspaces

Workspaces group tasks and rooms by context. A project can be linked to more than
one workspace. On first start after upgrading, uuBright Console creates `Default`, links
existing projects to it and assigns old tasks and rooms to it. Existing behavior
continues in Default.

Create a workspace in the app with **New workspace…** in the workspace switch (More on a
phone): enter a name. Git identity and plugins are under **Advanced options — optional**. No plugin is
needed to create a workspace; you can add one later in Workspace settings. The new workspace opens on
Start your Manager. Workspace settings renames it and changes its Git identity and plugins. The same is
in the [HTTP API](https://console.uubright.com/docs/api/#workspaces) and the [CLI](https://console.uubright.com/docs/cli/#workspaces).

The plugin list shows compatible folders with `.claude-plugin/plugin.json` in your repository folders
and in `~/.claude/plugins/marketplaces`; **Add by path** takes any other absolute path. A
template may suggest plugins, but does not turn them on. Incompatible discovered plugins are marked unavailable with a reason.
If a selected plugin becomes invalid, creation reports its name and how to continue without it; the form keeps your entries and no workspace is created until the request succeeds.
A plugin `.mcp.json` may contain a bare server map or an `mcpServers` wrapper; invalid server entries are refused.
A plugin runs code on this computer, so only the owner token can enable one, and only the
owner token can disable one, since that deletes its saved settings and secrets. On a paired
device or a relay phone the New workspace form says so instead of listing them, and Workspace settings
shows the add-ons read-only (see [What your tasks already have](#what-your-tasks-already-have)). Sign-ins (Claude Code,
Codex, GitHub) stay on the server CLI, and workspace settings shows the commands. There is
no way to delete a workspace yet.

A workspace's Git author and committer identity applies to its new tasks, which receive
`GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME` and
`GIT_COMMITTER_EMAIL`; these override a repository's local `user.*` settings.
For GitHub, use `login-github` in host mode or `set-github --token-stdin` for a
per-workspace token. The server passes only the selected workspace's GitHub
credential to a new task. In host token mode, HTTPS Git operations use `gh` as
their credential helper for that task without changing global Git settings.
For PR review statuses, that credential also needs **Commit statuses: Read and
write** in each repository. A classic personal access token needs the `repo`
scope. See [Local PR review](https://console.uubright.com/docs/lead/#local-pr-review) for the exact-head status
and the setup error shown when this permission is missing.
Repositories can opt into [automatic PR review](https://console.uubright.com/docs/lead/#automatic-pr-review)
through `.uubright/review.json` on the repository default branch. It is off by default;
workspace setup does not enable it for any repository.
Credentials cannot be set or read through HTTP.

Named workspaces use the host's existing Claude and Codex logins by default. No
new login is needed. Each agent has an independent login mode: `host` (the
default) or `own`. `login-claude` or `login-codex` opts that agent into `own`,
runs its normal login flow, and saves its home under `<data>/workspaces/<id>/`
(mode 0700). `use-host-login ID claude|codex` switches it back. On this host,
Claude Code's `claude auth login` writes `.credentials.json` in
`CLAUDE_CONFIG_DIR`; Codex CLI 0.163.0's `codex login` writes `auth.json` in
`CODEX_HOME`. Their settings live in `settings.json` and `config.toml`,
respectively. In `own` mode, account-route tasks require that workspace's login
and otherwise fail with the exact CLI command to run. Claude CCR-route tasks use
the gateway and need no Claude login. uuBright Console does not copy or link login
files, so OAuth token refresh continues against the selected agent home. Default
continues to use the host's existing agent configuration; uuBright Console doesn't edit
`~/.claude`, `~/.codex` or `~/.gitconfig`.

Enable a local Claude Code plugin directory with `enable-plugin`. It must have
`.claude-plugin/plugin.json`; `skills/`, `commands/` and `.mcp.json` are
optional. Claude Code 2.1.303+ loads each enabled plugin through its repeatable
`--plugin-dir` option, with or without a separate Claude login. In This Mac mode
a Claude task runs with `--strict-mcp-config`, which also skips the MCP servers of
`--plugin-dir` plugins, so the runner passes an enabled plugin's `.mcp.json`
servers itself (with `${CLAUDE_PLUGIN_ROOT}` filled in), named
`plugin_<plugin>_<server>` so their tools keep the names Claude gives plugin tools. In Codex `host`
mode, the task's own app-server process loads plugin skill directories through
`skills/extraRoots/set` and plugin MCP servers through `thread/start.config`
(also passed on resume); it uses the host's Codex login and does not change its
home. In Codex `own` mode, plugin skills are linked into that workspace's
`CODEX_HOME/skills` and `.mcp.json` servers go in a managed block in its
`config.toml`. Changes to enabled plugins apply to new tasks;
stopped tasks pick up changes on their next start, including login mode, agent
home, credential environment, plugin list and instructions. Running tasks keep
their launch arguments. Claude plugin `.mcp.json` HTTP `headers` become Codex
`http_headers`; supported Codex options such as `env_http_headers`, timeouts,
tool lists and `enabled` are preserved. An MCP field Codex cannot use causes
task preparation to fail with the server and field name. Workspace instructions are appended
to Claude's system prompt and passed as Codex developer instructions. Plugin
paths must be absolute and present. `enable-plugin` resolves a symlinked parent
once and stores the canonical path. Symlinks inside the plugin tree and plugins
inside uuBright Console's data directory are refused; the saved path is checked again
at task start. Plugins can execute code with the host account's permissions, so
enable only trusted directories.

A plugin with a `.claude-plugin/uubright.json` manifest is a **contract plugin**:
its settings and write-only secrets appear in workspace settings, the runner runs
its MCP servers (with secrets on file descriptor 3, out of the agent's reach), and
its servers can ask you to fill in forms. `enable-plugin` refuses a contract
version this console doesn't support. See [Plugin settings, secrets and forms](https://console.uubright.com/docs/plugins/).

## What your tasks already have

A workspace's plugins are called **add-ons** in the app. Most tasks need none, because a task already
starts with three layers. Workspace settings lists them under **Already available to every task here**:

1. **Built into Claude Code**: skills and commands such as `/code-review`, `/security-review`,
   `/simplify` and `/init`. Every Claude task has them. The list shows the names Claude Code reported
   when a task last started on this computer.
2. **From uuBright Console**: publishing to the Library, reporting progress and, for the Manager, starting
   and following Workers.
3. **From your Claude setup**: the skills, commands and enabled plugins in the Claude folder of the
   computer the tasks run on (`~/.claude`, or `CLAUDE_CONFIG_DIR`). They load when the workspace uses that
   computer's Claude sign-in, which is the default. With the workspace's own Claude login (`login-claude`)
   they don't load, and in Docker mode each task has a fresh Claude folder, so they don't load either.
   On **This Mac**, tasks run with `--strict-mcp-config`, which skips your own MCP servers (from
   `~/.claude.json` and installed plugins); skills and hooks still load. On a server, the same happens while
   an add-on with settings (a [contract plugin](https://console.uubright.com/docs/plugins/)) is on in the workspace.

A repository's own `CLAUDE.md` and `.claude/skills` also load in tasks that work in it.

**Add-ons** come on top, for this workspace's tasks only. They're under **Advanced: add-ons**, each with
its description and whether it has settings, runs a tool server or needs setup. **Recommended for this
workspace** shows the add-ons the workspace's template suggests (Teacher: `scimigo` and `scimigo-visuals`;
Code workspaces have none yet), with one tap to add; other plugin folders found on this computer are
under Advanced, with a search. Adding and removing are staged: **Save add-ons** saves them together and
then shows what the workspace now adds. Removing an add-on deletes its saved settings and secrets in
the workspace, so Save asks first. New tasks and chats get the change; running tasks keep what they
started with until they're restarted.

An add-on that your Claude setup already loads is blocked, because tasks would see two copies: the same
plugin enabled in your Claude settings, or a skill of the same name in `~/.claude/skills` (a linked folder counts, and so does a link to the add-on's own skill). The app says
which, and how to remove the host copy if you'd rather use the add-on. uuBright Console doesn't change
`~/.claude`. The check applies to the app and the HTTP API; the server CLI's `enable-plugin` doesn't make it.

The page reads only names: folder names in the Claude folder, and the `enabledPlugins` key of its
`settings.json` and `settings.local.json`. It doesn't open `~/.claude.json` or credential files. A paired
device or relay phone sees counts ("8 skills, 1 plugin"), not the names, including for Claude Code's
built-in list, and can't add or remove add-ons.

## Chat mode

Chat workspaces are being retired: the app no longer creates one or offers chat mode for a
workspace that isn't in it. A chat workspace you already have still opens in
[chat mode](https://console.uubright.com/docs/chat-mode/): Chats, Projects with memory, the Library and Apps instead of the
Manager. Mode in its workspace settings or **Use work mode here** moves it to work mode;
the app has no way back from there.

## SciMigo Studio workspace

SciMigo Studio is moving out of this app into its own at scimigo.com, and a new install has
no Studio workspace. This section describes a Studio workspace that already exists.

The host creates one **SciMigo Studio** chat workspace on startup. A compatible existing
non-coding workspace with that name is adopted. Its ID stays the same across restarts,
and existing chats, projects, settings, and other workspaces are left in place. A new
browser opens Studio first; a browser that already selected another workspace keeps
its selection. The workspace belongs to the selected execution computer. A paired
iPhone sees that computer's Studio workspace, and pairing does not sign in to Studio.
If the adopted workspace already had a configured Studio contract connector, its
existing token-based chats remain usable, including on a remote host. The device
sign-in gate applies to the new built-in connector path.

The built-in Studio **New chat** sends its first question into a native Studio thread on
**This Mac**. **Open Studio conversations** opens the same thread list without sending.
The thread page keeps an unsent draft locally on this Mac, reloads saved threads after reconnect, and offers
SciMigo device sign-in again if the account is revoked. It needs a SciMigo sign-in and
the reachable SciMigo question service; it needs no Claude or Codex binary or login,
repository, worktree, shell, or signed connector. It does not create a coding task.
Built-in Studio drafts stay in this browser's local storage, separately for each tab;
they are not synced through the console's cross-device draft API. A confirmed question
clears only its own local draft. An unconfirmed question remains available to retry.
Earlier task-based Studio chats remain available through **Earlier chats** on New chat
and in the desktop sidebar. Opening one shows its existing task conversation;
continuing it uses its original agent or connector. New chat still starts a native
question thread.
With **Keep me connected** off, New chat passes the current Mac connection to the
native page for that visit only. Refreshing that page requires reconnecting to This Mac.
When sign-in or the service is missing, New chat shows a single Studio setup card with
**Sign in to SciMigo** or **Try again**. Coding setup cards appear only in coding workspaces.

The native thread view also offers **Create slides**. Describe the content, select
language and presentation length, and review the exact request and server quote
before approving generation. You can include a local project's instructions and
saved notes; project files and coding repositories are not included. Decline starts
nothing. Once ready, open or download the available results and reopen the saved
conversation later. A PowerPoint download is offered only if the service actually
returns that format. This path needs the SciMigo creation service; it does not run
a local coding agent, use a remote execution host, or involve the relay. The native
API is available only to the local owner on This Mac. Audio/video and courseware
creation are outside this flow. Existing Studio workspaces with a configured legacy contract
connector continue using their earlier task-based chats and API token, including on a
remote host; the native path does not migrate or replace those chats.

The workspace can be browsed without a Studio account. Starting a native Studio chat
offers **Sign in to SciMigo**. The device code is
entered on `scimigo.com/device`; that page also offers registration. The draft remains
in the composer if sign-in is cancelled, expires, or the service is unavailable, and
the intended question is sent after sign-in succeeds. A saved session is reused and refreshed
on the execution host, scoped to this workspace. An invalid or revoked refresh token
returns to sign-in. Workspace settings also offer sign-in and sign-out. Claude/Codex
login is separate. A developer API token remains under Advanced plugin settings for legacy connectors.

For legacy task-based Studio chats, the connector is distributed separately from core as a signed, versioned release.
The host checks its signature and digest before enabling it, and uses a verified
previous version while offline. If a fresh install cannot download it, the
workspace explains that its tools are unavailable; the owner can retry from
Workspace settings. Provisioning and sign-in start no Studio job and enable no media or
spending. Narration and video remain off by default; chargeable operations still need
the connector's bounded quote and explicit approval.

Studio device sign-in currently works only on **This Mac** (local mode), where
the task sandbox denies the app's private data directory. Remote host-mode tasks
run as the service user and can read its files; the app therefore refuses to save
a hosted Studio session there. It does not copy a Mac session to a remote computer.

## Example: SciMigo on this host

Run these as the uuBright Console service user. Copy the ID printed by `create` into
the later commands:

```sh
npm run workspace -- create "SciMigo"
npm run workspace -- set-identity w-... "Your Name" you@example.com
npm run workspace -- enable-plugin w-... /mnt/data/src/scimigo-course-skills
```

With the server's owner token in `CCR_CLOUD_TOKEN`, start a Claude task in that
workspace through the API:

```sh
curl -sS -X POST http://127.0.0.1:8787/api/sessions \
  -H "Authorization: Bearer $CCR_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"workspaceId":"w-...","prompt":"Plan a SciMigo lesson"}'
```

Add `"agent":"codex"` to select Codex. Add `"modelRoute":"ccr"` to run Claude
through the configured CCR gateway. To use a separate SciMigo subscription,
run `login-claude w-...` or `login-codex w-...` on the server for that agent.

Named workspaces currently require host mode. Docker task creation refuses them
until their agent homes and plugins can be mounted without exposing other
workspaces. Host tasks still share the service user's filesystem, so a task can
read another workspace's files. Use separate hosts when the accounts require a
security boundary. The app opens on **Needs you**, an inbox across all workspaces. On phones, use the
bottom tabs: **Manager**, **Inbox** (Needs you, with a count), **Tasks** and **More**. Deliverables is the first item
under More, and a **Deliverables** link sits beside the Manager's Chat and Team log tabs. A task, a chat, a settings
page or a deliverable opens full screen, like a conversation in Messages: a top bar with **‹ Back** (named for the list
you came from), the title with its state under it, and **⋯** (the task's menu, with **Report a problem…**). There's no
tab bar there, so the conversation takes the screen. Back, the browser's back, Android's back and the iOS edge swipe all
return to the list where you'd scrolled it, and a link to a task opens it with Tasks underneath (the Manager's
overview for the Manager and its workers). On a phone the **Manager** tab is an overview: the goal and its step, what
needs you, the Manager's latest reply (**Conversation ›** opens it, with **‹ Manager** to come back), its workers with
their states (finished ones fold behind one row) and the latest deliverables. **Show the four steps** in the Manager's
**⋯** opens this overview. Launched without a
link, the phone opens on Needs you when something waits there, and otherwise on the Manager tab of the workspace you
used last; what arrives later only adds to the Inbox badge. Wide screens have a workspace sidebar whose top row is
the workspace switch, **Jump to a task** (🔍, or Cmd/Ctrl+K) and **New task** (＋); the switch's menu also
holds **Workspace settings**. Jump to searches tasks and rooms; paste a task id (`s-…`), or its first six
or more characters, to find that task. In the sidebar, **Needs you** lists tasks blocked
on a question, approval, held message or browser hand-off, marked in amber;
**Ready to review** marks finished work you haven't opened yet, with its
violet chip. The open task has an accent bar and stays scrolled into view. Drag
the sidebar's right edge to resize it (220–480 px), or focus the handle and use the
arrow keys; double-click it to reset. The width is remembered on this device.
Collapse the sidebar with the button at its top, or ⌘B on a Mac (Ctrl+B elsewhere), to give
the conversation the full width. A slim rail stays with a button to show the sidebar
again and the **Needs you** count. The collapsed
state is remembered on this device, and showing the sidebar again restores its width.
The selected workspace persists on this device;
`#w=<id>` selects one directly. Older task and room links still open their records
in the correct workspace. With only Default, the switcher and inbox filter hide.
Task ids in agent replies, room posts and inbox cards link to their task, in
whichever workspace it lives, with its title as the tooltip; so do lead workers'
`w-…` handles in room posts. Ids in code stay plain text so commands copy cleanly,
and ids of tasks the server no longer has are not linked.
Inbox cards name the reason each item needs you. Questions and approvals appear
before room hand-offs, then finished work. Select a summary to see its actions;
reply fields appear when you choose **Answer**.
The line below **Needs you** counts actions in the selected inbox scope. **All workspaces**
includes other workspaces even while the sidebar is showing Default; choosing a named
workspace limits the list and count to that workspace on the current computer. Each
action card identifies its repository (or says there is none), the owner, wait age
when the event has a timestamp (otherwise **time unavailable**), and the next action.
A PR that is ready for the owner's merge has a **Merge PR** action. A held PR appears
separately under **Held PRs**, with its hold
reason, the responsible author, reviewer, Manager or GitHub actor, that actor's next
step, and a link to GitHub; it does not count as an action or offer a merge button.
PR messages routed automatically to an agent remain outside the owner's action count.
In the finished group, use **Mark all finished as seen** or select finished
tasks and choose **Mark seen**. The action clears those items and their attention
badges on this device; **Undo** restores them for a few seconds. With a workspace
filter selected, the action applies only to finished tasks in that workspace.
Questions, approvals, hand-offs and held messages keep their own actions.

The task list starts with the workspace's [Manager](https://console.uubright.com/docs/manager/), with its workers
nested under it, then pinned tasks, then the rest in one stable list. Choosing a
workspace opens its Manager, or **Start your Manager** when it has none. **Change Manager…**
offers **Cancel**, which returns to the current Manager and keeps any draft. On a phone,
browser Back from Change Manager returns to the Manager overview. Switching
workspaces opens that workspace's normal Manager view or start form. The New task
form shows that workspace's plugin starters as chips above the
prompt: the cards a plugin declares ([Starters](https://console.uubright.com/docs/plugins/#starters)), or else its commands. Agent and project are compact selectors; projects linked to the workspace
appear there, and a workspace without linked projects starts with **No repository
(scratch)**. The line above **Start task** reads *agent · project*; open it to see
the server, repository path and branch the task will use. **Add a project…** opens the repository finder; **Options** holds
permissions, response style and model access. `GET /api/workspaces/:id/starters`
returns each starter (see [API](https://console.uubright.com/docs/api/)). Choosing one opens its form, if it has one,
then prefills the prompt, the Claude slash command or Codex instructions.
Workspace settings show defaults, enabled plugins and credential status; credential
changes remain CLI-only, with one exception: a contract plugin's secrets can be
entered there, masked and write-only ([Plugin settings](https://console.uubright.com/docs/plugins/)). Minting
credentials stays CLI-only. See [Default models](#default-models) for the one default
you can change there. Server settings hold devices, notifications, messaging and
setup.

**Deliverables** (formerly Outputs, or the Library) lists a workspace's published
results and drafts, newest first. It shows the newest version of each task
deliverable with its [state](https://console.uubright.com/docs/artifacts/#deliverable-states), filters by state,
kind and task, and the next step on each card: **Approve** or **Mark published…**.
Open a card to preview a video, image, PDF, slide deck or Markdown document, switch
versions, download it or open it in a new tab. Other files can be downloaded. A task
publishes a deliverable with its artifact tool; files in `.ccr/artifacts/` appear as
drafts until published.

When a task has published artifacts, its latest deliverable appears above the
conversation. You can approve a ready version or use **Revise** to start a follow-up
message about that version. Revise fills the composer; it does not send the message.
Drafts stay in a small list below the published deliverable. Tasks with only code
changes keep the usual task view and change controls.

See [Artifacts](https://console.uubright.com/docs/artifacts/) for publication, drafts, versions and safe serving.

## Default models

Each workspace can have a default model for Claude Code and one for Codex. A new task
whose **Model** picker says **Default** starts on the workspace's model for its agent;
without one, the agent uses its own setting. A model you choose for a task wins over
the default.

To set them, open **Workspace settings**, choose a model under **Default models** for
each agent, and select **Save default models**. **Agent's own setting** clears a
default. You can also pick a model on the New task form and select **Use for new tasks
in this workspace**; that also accepts a custom model ID from **Options**.

Claude Code's list follows the workspace's default model access. If a task's model
access can't run the workspace's Claude Code default, for example a CCR model on a
task that uses the Claude account, the task uses Claude Code's own setting instead.

Through the API, send `PATCH /api/workspaces/:id` with
`{"defaultModels": {"claude": "sonnet", "codex": null}}`; `null` clears a default. See
[HTTP API](https://console.uubright.com/docs/api/#workspaces).
