A workspace is a project that orchestrates work across several repository projects. Your team links its repositories once, then starts each piece of work from a Jira card: crewkit cuts one branch and worktree per repository, follows the branches through pull request and merge, and posts each step to Slack.
What a workspace holds
- Member projects — the repository projects it works across. Their repositories, skills and agents are available in the workspace.
- Repositories — each with a remote URL and the base branch work is cut from and merged into.
- Members and leads — see Roles.
- A Jira project key — the project a work item's card belongs to. Leave it empty to fall back to the member projects' keys.
- A Slack channel for work updates — where work items post when they open, are assigned, push a branch, open or merge a pull request, need input, change progress, wait for or get approval, and close.
- Agent settings — the permissions and MCP servers members get in Claude Code inside the workspace folder and its worktrees under
work/.
Before you start
Every workspace guide assumes:
- CLI 0.7.11 or later, signed in — see Installation.
- The role each step names, from the table below.
Roles
Workspace roles sit on top of your organization role. Managers, admins and owners act as leads in every workspace.
Creating a workspace makes you its lead. A workspace created before this has no lead until a manager or above adds one. Until then, managers and above see a banner on the workspace page: "This workspace has no lead. Add one in Members." It links to the Members card and goes away once the workspace has a lead. Nobody else sees it. Every other workspace role is given in its Members card, by a lead or a manager or above.
| To | You need |
|---|---|
| Create a workspace, link a repository to it | Developer or above |
| Start, save, open pull requests for, assign and close work | Workspace member or lead with developer role or above, or manager or above |
| Manage members and member projects, set the Jira key and Slack channel, approve features | Workspace lead, or manager or above |
| Edit agent settings | Workspace lead with developer role or above, or manager or above |
| Change a base branch or repository commands, create a team agent | Manager or above |
| Connect Jira, Slack or a code host; link a repository to a code host | Admin or owner |
Work items
A work item is one piece of work, keyed to a Jira card:
| Kind | Starts as | Worktrees |
|---|---|---|
| Fix | Open | Cut at once, one per repository you pick |
| Feature | Proposed, keyed to an Epic | Cut after a lead approves it |
Each work item has a handle made from its card key and title, like crew-123-fix-login-redirect, and a branch per repository, like CREW-123-fix-login-redirect. Its worktrees live under work/<handle>/<repository> in your local workspace folder.
As its branches change, the item moves through Open, Active (commits, a save, or a pull request closed without merging), In review (a pull request is open), Blocked (a session needs input) and Closed (its pull request merged, or someone closed it). The workspace page groups items by these states in its Work card.
Pull request states and merges reach crewkit only through the code host's webhooks: see Connect your code host. Without them an item stays In review after its merge until someone closes it.
Jira status
crewkit reads each card's Jira status (and an Epic's child issues) about every 15 minutes and shows it in the Work card, crewkit work list and crewkit work show. It never transitions, comments on or edits a card: you move cards in Jira as usual.
The local workspace folder
crewkit work runs inside a folder that holds a clone of each repository, set up by crewkit init --workspace, or by crewkit init --workspace --join for a workspace that already exists:
acme/
├── .crewkit/config.toml # the workspace this folder belongs to
├── api/ # your clone of acme/api
├── web/ # your clone of acme/web
└── work/
└── crew-123-fix-login-redirect/
├── api/ # worktree on CREW-123-fix-login-redirect
└── web/Sessions and repositories
A session started with crewkit code in a clone or worktree is attributed to the repository whose remote matches its git remote. A session started in the workspace folder itself is attributed to the linked repositories found in its child folders. In CI, name the repository with --repo-id <id> or CREWKIT_REPOSITORY_ID.
Each conversation shows its repository. In the project's Conversations list, a project with several repositories has a repository filter.
Each repository has a session visibility, set when the repository is created through the API (session_visibility) and not changeable afterwards:
| Visibility | Who sees its sessions | Who can set it |
|---|---|---|
| Public (default) | Everyone who can see the project | Anyone who creates the repository, by leaving it unset; managers and above, by naming it |
| Restricted | The session's owner, managers and above | Manager or above |
| Private | The session's owner, admins and owners | Admin or owner |
A session attributed to several repositories follows the most restrictive one. A session attributed to no repository, in a project that has a restricted or private repository, is treated as restricted.
How-to guides
- Set up a workspace — create it, add members, link repositories, connect your code host, Jira and Slack.
- Fix a ticket end to end — start, save, open pull requests, close.
- Ship a feature with approval — propose, approve, follow the Epic's progress.
- Hand off work and set agent settings — assign, pick up on another machine, repository commands and agent settings.