--- source: CrewKit documentation url: https://crewkit.io/docs/workspace-handoff.md title: "Hand off work and set agent settings" description: "Assign work, pick it up on another machine, declare repository commands and share the workspace's agent settings." --- You end up able to move work between people and machines without pushing half-done branches, and with the commands and Claude Code settings your team shares declared once in the workspace. **You need:** - What every workspace guide needs — see [Before you start](/docs/workspaces#before-you-start) — and to be a workspace member to hand off work, a manager for repository commands, and a lead for agent settings. - A workspace folder — see [Set up a workspace](/docs/workspace-setup). --- ## Hand off a work item ### 1. Save where you are On the machine you are leaving: ```bash crewkit work save crew-123-fix-login-redirect ``` See [Save work in progress](/docs/workspace-fix#3-save-work-in-progress). ### 2. Assign it ```bash crewkit work assign crew-123-fix-login-redirect sam@acme.example ``` ``` Assigned crew-123-fix-login-redirect to Sam ``` The assignee must be a workspace member. You can also pick the assignee in the item's row of the **Work** card, or run `crewkit work update crew-123-fix-login-redirect --assignee sam@acme.example`. Slack posts the change. ### 3. Pick it up on the other machine In a workspace folder on the other machine, with clones of the same repositories: ```bash crewkit work pickup crew-123-fix-login-redirect ``` ``` • /Users/sam/code/acme/work/crew-123-fix-login-redirect/api save 3f9c2a1 ``` crewkit creates each worktree on the work branch and restores the last save over it as uncommitted changes. With no save it starts from the pushed branch (`pushed `). Carry on, and `crewkit work save` from here. --- ## Repository commands Managers declare each repository's setup, test and gate commands, once for everyone in the workspace. 1. Open the workspace's **Settings**. In the **Repositories** card, each repository shows **Commands** (or **No commands declared**). 2. Click the pencil next to it. 3. Fill in **Setup commands**, one per line (e.g. `bin/setup`, `npm ci`). Click **New component** for each part of the repository and give its name, path, test command (e.g. `bin/rails test`) and gate commands. 4. Click **Update**. Write each command as shell words, quoting arguments with spaces. Commands are stored as argument lists, not shell lines, so pipes, `&&` and variables are kept literally. --- ## Agent settings Agent settings are the permissions and [MCP servers](/docs/mcp) workspace members get in Claude Code. ### Set them 1. Open the workspace's **Settings**. The **Agent settings** card shows the **Allowed** entries (each marked **vetted** or **unvetted**), the **Always denied** entries crewkit fixes, and the **MCP servers**. 2. Click **Edit**. 3. In **Allowed (one entry per line)**, list permissions, e.g. `Read` or `Bash(npm test *)`. Click **New server** to add an MCP server with a name, a type (`http` or `sse`) and an `https` URL. 4. Click **Update**. ### What each member gets When a member runs `crewkit code` (or `crewkit init --workspace`) in the workspace folder itself, crewkit writes these into that folder: - `.claude/settings.json` — the allowed entries plus the fixed deny list. crewkit owns this file; it never touches `.claude/settings.local.json`. - `.mcp.json` — the MCP servers. Vetted entries are written straight away. Unvetted entries and MCP servers wait for that member's own yes on a terminal: ``` Workspace agent settings, last changed by Alex at 2026-10-14T12:00:00Z. Unvetted permissions — Claude Code will run these without asking you: + Bash(npm test *) MCP servers — contacted from this machine; they see tool arguments (prompts, code): + docs (http) https://mcp.acme.example/mcp (+ = new since you last accepted) Write these to this workspace? ``` Any change to the list asks again. Signing in to each MCP server stays per person, in Claude Code. Worktrees under `work/` do not get these settings yet: a session started in a worktree, or in one of the clones, runs without them. --- ## If it stops - **`nothing saved or pushed`** on pickup — nobody has saved or pushed the work yet. Ask the previous owner to run `crewkit work save`. - **`… has uncommitted changes; save or discard them first`** — a worktree for the item already exists on this machine with changes in it, and pickup would write the saved state over them. Saving does not help: `crewkit work save` leaves the worktree as it is. To take the saved state, set your changes aside first — in the worktree, `git stash push -u` (or copy the changed files elsewhere) — then run `crewkit work pickup crew-123-fix-login-redirect` again, then `git stash pop` to reapply yours on top, resolving any conflicts. Anything you neither stash nor copy is lost. - **`… is not at the saved parent …`** — the worktree's branch is on a different commit than the one the save was made on. Bring the branch to that commit (for example `git pull` when the other machine pushed it), then pick up again. - **``the saved state moved; run `crewkit work pickup` first``** — another save of this branch reached origin while yours ran, usually from another machine, so yours was not recorded. Either: - keep yours: run `crewkit work save` again. It replaces the other save, which crewkit then no longer points to. If it fails the same way again, the other machine's save is on origin but not recorded yet; it is recorded on that machine's next save. - take theirs: set your changes aside, pick up and reapply, as for **`has uncommitted changes`** above. - **`saved ahead of pushed`** in `crewkit work show` — the last save holds work the pushed branch does not. - **`Agent settings: held back 2 unvetted entries and 1 MCP server awaiting your yes`** — the sync ran without a terminal (or with `--yes`). Run `crewkit code` in the workspace folder, in a terminal, to review them. - **`Agent settings: left .claude/settings.json unchanged — …`** — crewkit will not overwrite a `settings.json` it did not write, or one the folder's git checkout tracks. Remove (or untrack) the file to let crewkit manage it. - **No pencil or Edit button** — your role cannot change it; see [Roles](/docs/workspaces#roles). --- ## Next steps - [Workspaces](/docs/workspaces) - [CLI reference](/docs/cli)