Hand off work and set 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 — 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.

Hand off a work item

1. Save where you are

On the machine you are leaving:

crewkit work save crew-123-fix-login-redirect

See Save work in progress.

2. Assign it

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:

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 <sha>). 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 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.

Next steps

• Workspaces
• CLI reference