claude-crew

One Claude Code session coordinates, the others build and test. A three-role protocol for running several sessions on the same repository without two of them writing the same file.

Open several Claude Code sessions on one repo and they will happily overwrite each other: one commits another's half-finished work, two switch the same branch, both edit the same file from opposite ends. claude-crew gives them a protocol. One session becomes the coordinator, keeps a task board, and hands out file-scoped assignments. Workers own their files and build. Testers exercise the result in a real browser and return a verdict.

The three roles

Role	Owns	Writes	Ends its turn with
Coordinator	the board, the routing, git	nothing but the board	a commit, once you approved it
Worker	a set of file globs	the code	RESULT DONE with evidence it ran
Tester	the browser and the test surfaces	nothing at all	VERDICT PASS / FAIL with a reproduction

A crew runs fine without testers; verification then falls back to a worker that did not write the change. It never runs with two coordinators.

What it does

• File-level ownership. Assignments are split by disjoint path globs, never by topic. Two workers can never hold the same file.
• Routing by model and effort. Each session reports what it runs on. Architecture and verification go to the strongest model at high effort, mechanical edits go to the cheapest one that can do them.
• A board that survives compaction. State lives in .coordination/board.md, not in anyone's context window.
• Verification as its own lane. A task reaches DONE only on a tester's VERDICT PASS. A worker's own green test run is evidence, not a verdict.
• Loops that run in the right place. "Keep fixing lint until it is clean" becomes a capped loop assignment a worker runs end to end, so the coordinator stays free to answer everyone else.
• The coordinator never writes code. Not one file, not one typo fix. It reads, routes, reviews and commits. That is the whole rule the design rests on.
• Crew sessions, not subagents. Every unit of work runs in a real session you can see, that holds its own permissions and can refuse.

Install

git clone https://github.com/DevGonzi/claude-crew.git
cp -r claude-crew/skills/crew ~/.claude/skills/crew

Per project instead of globally:

cp -r claude-crew/skills/crew .claude/skills/crew

Restart Claude Code, then /crew is available in every session.

Use

Open one terminal per session, all in the same repo.

Session 1:  /crew coord     the coordinator
Session 2:  /crew worker    builds
Session 3:  /crew worker    builds
Session 4:  /crew test      verifies

The coordinator takes a census, writes the board, and routes from there. You talk to the coordinator only; it splits the job, answers the others' questions, collects verdicts and tells you what is left.

Called bare, /crew picks the role itself: an incoming VERIFY means tester, any other crew message or an existing coordinator means worker, otherwise coordinator.

Stop with stop crew in any session.

How it works

Sessions message each other with SendMessage in a fixed vocabulary. One verb per message, first line:

Verb	Direction	Means
HELLO	worker, tester → coord	I exist, here is my state and role
CENSUS	coord → all	Report your state now
ASSIGN	coord → worker	One task, file-scoped
STATUS	worker → coord	ACK, REJECT, or ITER <n> mid-loop
RESULT	worker → coord	DONE or BLOCKED, with evidence
VERIFY	coord → tester	Exercise this claim and report what happens
VERDICT	tester → coord	PASS, FAIL or BLOCKED, with evidence
ASK / ANSWER	any	A question that changes what gets built or tested
PING	coord → any	Are you alive, one line back
NOTICE	any	Something that affects other sessions
RELEASE	coord → all	Drop locks, idle

An assignment is only an assignment if it can be checked:

ASSIGN T2
GOAL: quota reset handles orgs outside UTC
FILES: src/jobs/quota.ts, src/jobs/quota.test.ts
READONLY: packages/database/**
DONE WHEN: npm test -- quota passes, including a case for UTC+2
CONSTRAINTS: no commit, no push, no branch change
REPORT: STATUS when you start, RESULT when finished or blocked

And a verdict is only a verdict if somebody watched it behave:

VERDICT FAIL T2
RAN: npm test -- quota → 11 passed, 1 failed (quota.test.ts:88)
REPRO: set org timezone to UTC-5, open /settings/quota, reset renders as 19:00 the previous day
EXPECTED: 00:00 local. ACTUAL: 19:00 previous day, so the offset is applied twice
EVIDENCE: screenshot ss_quota_utc5, console error at quota.ts:41
SCOPE: only the display path, the stored value is correct

The reproduction goes back to the worker verbatim. Paraphrasing it loses the test.

The rules that make it work

• Git belongs to the coordinator. Workers never commit, push or switch branches: they share a working tree with sessions that would lose their changes. The coordinator stages by path, and only after you approved that specific commit.
• Nobody tests what they wrote. A verdict from the session that made the change is not a verdict.
• Testers write nothing. Read-only on the repo, no fixes, no re-scoping. A tester that fixes a bug has just written untested code and destroyed the reason it was a separate session.
• No peer permission. A coordinator is a peer, not an authority. Force operations, production access, deleting data, spending money: those still come back to you, in the session that would perform them.
• No credentials, ever. A test that needs a login the session does not already have is VERDICT BLOCKED: needs user approval, not a tester typing a password into a form.
• Report the truth. Failing tests are reported as failing, by the worker, by the tester and in the summary you get.

Requirements

Claude Code with SendMessage and ListAgents available (multi-session messaging). Without a message channel the skill says so in one line and stops.

Browser testing uses whatever browser tooling the session has. Testers prefer the in-app browser for local and staging URLs, and reach for a signed-in browser only when the assignment says the test needs an account.

Sessions address each other by the name ListAgents prints, copied verbatim. Nothing needs renaming, though titling your sessions makes the board easier to read.

Layout

skills/crew/
  SKILL.md        role selection, addressing, vocabulary, shared rules
  coordinator.md  board, census, routing, splitting, loops, testers, commits
  worker.md       reporting in, assignments, loop execution, escalation
  tester.md       verdicts, browser testing, what a pass means

SKILL.md is the entry point and stays small; the role file is read only by the session that took that role.

License

MIT. See LICENSE.