Appearance
Workspaces
A workspace is where your agents work: a folder on every agent assigned to it, the git projects cloned into that folder, the instructions and tool configuration agents read there, and the tracker project whose tickets route to it. This page explains what a workspace holds, how to create and set one up, how its configuration reaches agents, and how tickets find their way into it.
What a workspace holds
| Part | What it is |
|---|---|
| Path on VM | The folder under each agent's home directory that the workspace deploys to, for example ~/workspace |
| Git projects | The repositories agents clone into the folder, each into its own subpath |
| AGENTS.md | The instructions agents read when a session starts in the workspace |
| .mcp.json | The MCP servers available to agents in the workspace |
| Skills | Named Claude Code skills, delivered to .claude/skills/ in the workspace folder |
| Agents | The agents that host the workspace. One agent can host several workspaces |
| Work intake | How work arrives: a linked Jira project, Linear team or Notion data source, or internal Kadmo tasks |
Every account starts with one workspace, Dev Workspace, at ~/workspace. Work is started in a workspace: tasks, playbook runs, jobs and Ask threads carry the workspace they belong to.
The workspace switcher at the top of the sidebar sets which workspace the daily pages show. All workspaces shows the whole account.
The Workspaces page
Open Settings at the bottom of the sidebar, then Workspaces. Each card shows:
- the workspace's label and slug, and its linked tracker project if there is one;
- its state: ✓ Ready, Setup n of 5 while setup is unfinished, or Archived;
- the path on the agents, the number of agents, and when it last changed;
- Run, which starts a workflow or playbook here, and a menu with Edit, Archive and Delete.
Clicking a card opens the workspace's Overview. Only admins create, archive and delete workspaces; Users see the page read-only.
Create a workspace
Press Create workspace (Create your first workspace on an empty account) and fill in:
| Field | Meaning |
|---|---|
| Label | The name shown everywhere (required, up to 120 characters) |
| Slug | Lowercase letters, numbers and dashes; derived from the label if left blank |
| Path on VM | The folder under the agent's home directory (~/ + your folder). It follows the slug until you edit it. Letters, numbers, ., - and _, with / for nesting |
| Color | The accent: Orange, Sky, Emerald, Violet, Rose or Slate |
| Icon | The workspace's mark |
The new workspace has no agents and no code yet. Its Edit page walks you through the rest.
Archive and delete
Archive stops dispatch to the workspace: the card reads Archived, and queued work waits until it is switched back on with Active (dispatchable) on the Edit page. Delete unassigns the workspace from all agents and removes its configuration; repositories already cloned on agents stay where they are. A workspace with active jobs cannot be deleted: wait for them to finish or cancel them first.
The Overview
The workspace's Overview is the daily page for one workspace: what needs you, the planned work with a strip of the last 24 hours per agent (page back with ‹ ›), outcome tiles for today, 7 days and 30 days, and ledgers of the workspace's Agents, Roles and Playbooks. Run job starts work by hand, and Workspace settings opens the Edit page.
Set up a workspace
The Edit page has three tabs, Settings, Agents and Code & files, with the Workspace state panel beside them.
Setup and readiness
While setup is unfinished, a band above the tabs names the next step and offers one button for it. There are three steps:
| Step | Done when | The button |
|---|---|---|
| Assign agents | At least one agent hosts the workspace | Assign agents, or Go to Agents page when the account has no agents yet |
| Connect code | At least one git project is attached | Add a Git project |
| Intake | Always done. It reads Route Jira work (or Linear, Notion) when a project is linked, Internal tasks when none is, or Dispatch by hand when you chose that | — |
The Workspace state panel draws the path work takes as five stations, each with a lamp and a readout. The Setup n of 5 on the Workspaces card counts the stations that are on.
| Station | Readout |
|---|---|
| Dispatch | on, or paused |
| Agents | How many are assigned and how many are online |
| Code | How many repos, and the first one |
| Intake | The linked project, internal tasks or manual dispatch |
| On agents | in sync · applied and when, not applied yet, or never applied |
Under the stations is the verdict:
| Verdict | Meaning |
|---|---|
| Ready for work | Dispatch is on, agents are assigned and code is attached. Linked tickets, internal tasks and manual runs dispatch here |
| Ready · setup unfinished | Work can run, but no repository is attached. Connect code so agents have a repo to work in |
| Not ready — no agents | Assign agents first |
| Not ready — dispatch paused | Switch Active (dispatchable) back on |
Settings tab
Saved with Save settings, which never contacts agents.
- Identity: a logo (an image up to 256 KB) or a built-in mark, the label and the accent colour.
- Work intake: the tracker project this workspace serves (see Tracker routing), the Task key prefix for internal tasks, Dispatched by hand, and Active (dispatchable). With Active off, the scheduler dispatches nothing here and queued work waits.
- Auto-discovery: how agents map the workspace's software into the skill pack: Target confidence, Max dispatches, Min spacing (sec) and Enabled on dispatch. Live progress is on the Overview.
- Delete workspace (admins).
Agents tab
Which agents host the workspace. The roster lists the assigned agents with their presence and whether they hold the current configuration; the pool below lists the account's other agents, each with Assign. Assigning and removing take effect immediately and are not part of either save button. A newly assigned agent receives the workspace configuration at once; an offline one receives it when it next checks in. To add agents to the account, see Create an agent.
Code & files tab
Everything on this tab lands on the assigned agents when you press Save & apply to agents. Nothing reaches an agent before that.
- Deploy location: the Path on VM. Changing it re-clones the repos on the next apply.
- Git projects: Add project with the Repo URL (GitHub, GitLab or Bitbucket over https, for example
https://github.com/owner/repo), a Display name, the Default branch and a Subpath. The subpath is required: each repo clones into its own folder inside the workspace, never into the workspace root. An optional App contract (app dir, dev port, dev command, dev env) tells an editing session how to run the repo. For private repositories, connect the git host under Integrations first (see Integrations). - Skills: drop
.zipor.mdfiles; each becomes a Claude Code skill named after the file. - Config sets: the workspace's AGENTS.md and .mcp.json, edited in place or with Upload & replace.
.mcp.jsonmust be valid JSON, and${VAR}references expand from the agent's environment when a session starts. The built-in pair is calleddefault; agents use it unless pinned to a named set.
The same files also appear under Files in Settings.
How configuration reaches agents
The header of the Edit page keeps the two save actions in view: Save settings for the Settings tab, and Apply to agents (Save & apply (n) while there are unsaved changes) for the deploy. Applying an unchanged workspace again is the way to repair an agent whose files drifted.
An apply treats each assigned agent according to its state:
| Agent | Save & apply to agents | Apply to Busy | Later, on its own |
|---|---|---|---|
| Idle | Gets everything: the files and the repos | Gets everything | — |
| Busy (working on a job) | Skipped, reported busy | Gets AGENTS.md, .mcp.json and its environment, but not the repos, so its working tree is never switched mid-job | Gets everything once idle |
| Offline | Gets everything on its next check-in | Gets everything on its next check-in | — |
Apply to Busy is offered only when an agent was skipped as busy, and Retry failed only when a delivery failed. You do not have to press anything after an edit: an idle agent that holds older configuration picks up the change on its next health report. The On agents station shows when configuration last reached the agents.
Tracker routing
A workspace can serve one tracker project: a Jira project, a Linear team or a Notion data source. The link is the single routing rule between your tracker and the fleet: a ticket from that project is worked in this workspace, at its path, by its agents, and every automation and playbook run started from such a ticket inherits that.
| Rule | Details |
|---|---|
| One per workspace | A workspace links one project, and a project links to one workspace in the account |
| Jira project key | Letters, digits and underscores, starting with a letter, for example ACME |
| Linear team key | Letters, digits, dash or underscore |
| Notion data source | Picked from the list. A database with several data sources shows one option each |
| Unlink | Leave the field empty |
When the tracker is connected, the field is a list of its projects; otherwise you can type the key. If the key is already linked to another workspace, saving is refused with a message naming that workspace's slug.
Without a link, tasks you create in the workspace are internal tasks, keyed with the Task key prefix (for example DW-1, DW-2): 2 to 5 letters or digits starting with a letter, unique in the account. The prefix may not equal a tracker project key linked in the account, and TASK is reserved. Changing the prefix affects new keys only. Tick Dispatched by hand if nothing should route work here at all and runs are always started manually.
Connecting the trackers themselves: Jira, Linear, Notion.
The task pool
Each workspace feeds the account's task pool on the Tasks page. You bring in many tickets at once (a pasted list, an epic, a tracker query, or internal tasks), review and approve them, and Kadmo releases them as playbook runs in dependency order: a ticket blocked by another in the pool never starts before its blocker is done. Tickets are routed to workspaces by the tracker link above. See Working with tasks.
Related
- Getting started: the first workspace and the first run.
- Agents: the fleet that hosts workspaces.
- Playbooks: what runs in a workspace.
- Skill packs: the knowledge agents read, and auto-discovery.