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 and the CLI.
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). 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 for the exact-head status and the setup error shown when this permission is missing. Repositories can opt into 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.
#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:
- Built into Claude Code: skills and commands such as
/code-review,/security-review,/simplifyand/init. Every Claude task has them. The list shows the names Claude Code reported when a task last started on this computer. - From uuBright Console: publishing to the Library, reporting progress and, for the Manager, starting and following Workers.
- From your Claude setup: the skills, commands and enabled plugins in the Claude folder of the computer the tasks run on (
~/.claude, orCLAUDE_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.jsonand installed plugins); skills and hooks still load. On a server, the same happens while an add-on with settings (a contract plugin) 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: 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:
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-skillsWith the server's owner token in CCR_CLOUD_TOKEN, start a Claude task in that workspace through the API:
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, 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), 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). 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). Minting credentials stays CLI-only. See 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, 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 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.