Docs › Crew: several AI agents, one Master

Crew: several AI agents, one Master

Beta. Crew works and is part of the licence, but it is newer than the core and may change between versions. It needs accounts or API keys for the agents you add (see Requirements).

Give one task to a Master AI. It reads the code, splits the work into parts and gives each part to an agent: a Claude account, ChatGPT through Codex, Gemini, a local model on your own machines, Kimi and other APIs, or Claude Code sessions in the cloud. When a part is finished, the Master reviews it. It either merges the part or sends it back with notes. At the end it reviews the whole result and writes you a summary. You get one branch to merge.

It's in the dashboard, on the Crew tab. A plan waiting for your approval shows in a banner at the top. The task list filters to what needs you (plans to approve, failed tasks), what is active or what is finished, and searches titles, repositories and branches. What you type for a new task is kept as a draft until you start it (⌘/Ctrl+Enter starts it). How the Master works folds away under a one-line summary of its settings.

How a task runs

1. You describe the task and pick the repository: tap a recent one (your latest Claude Code projects), type its path, or use Browse… to walk this computer's folders (git repositories are marked). The branch to start from is optional; its list shows the repository's branches. 📎 Attach files (or paste or drop them on the form) adds screenshots, mock-ups, specs or logs: up to 10 files, 15 MB each. The Master and every agent can read them, and the pictures are shown with the task.
2. The Master plans. It reads the code without changing it. Then it splits the task into one to six parts, picks an agent for each and adds a check command when one fits (such as npm test). Parts that build on others wait for them.
3. You approve the plan (unless you switched that off). You can give a part to another agent, leave a part out, or write notes and ask for a new plan. Above the parts, What this task may do says, before anything runs: the agents it will use (with the parts each gets), where each one works and how it is paid for, the repository, the branch it starts from and the new branch, the linked folders next to it (when that is on), the check commands the Master wrote and where each runs, what is pushed, and the estimated cost. The card follows your changes: give a part to another agent or leave one out, and the agents and the estimate change with it. Below it, Spend at most $X on this task sets a cap (see A cap per task).
4. The agents work at the same time. Each part gets its own git worktree and branch, so agents never edit the same files. Tests and builds go to your spare machines through sparehand run --or-local.
5. The Master reviews each part. It sees the diff, the agent's summary and the check's result. Then it accepts the part or sends it back with concrete notes. By default a part gets up to two more rounds. An accepted part is merged into the task's branch crew/…. When a merge conflicts, the Master resolves it. The Master can run checks itself while it reviews: on a spare machine through sparehand run, plus syntax checks such as bash -n. It still can't edit anything.
6. The final review. Once every part is in, the Master runs the final check and reviews the whole change. Then it writes the summary. The dashboard shows the command to merge the branch.

Nothing is pushed (except for parts given to the cloud, see Parts in the cloud), and your own checkout is never touched: the agents start from the branch's last commit, so uncommitted changes aren't part of it. The agents' checkouts live in Sparehand's own folder, on their own: a path like ../other-repo (in the task or in a script) points at nothing there. When a task needs the repositories next to yours (a sync script, a change that spans two repositories), turn on Link the repositories next to it under How the Master works: the git repositories next to your repository are then linked beside each checkout, so ../other-repo works as it does in your checkout. It is off by default, because it puts those folders in every agent's reach; only repositories are linked, and never when your repository sits in your home folder itself (everything there would be in reach).

When an agent hits its usage limit, it rests until the limit resets (or for 30 minutes, when its tool doesn't say when) and another agent takes its part. If an agent fails a part outright, another agent tries it. You can also give any part that didn't make it another try, with the agent of your choice.

Merging it for you (off unless you turn it on). By default a finished task waits for you to merge it: the dashboard shows the commands. In Crew's settings, "When a task is ready" can merge it instead: onto the branch it started from, as one commit named after the task, once the Master's final review says it's ready, every part is in and the final check passed. "Unless a part needs a manual check" leaves those for you. It never merges over uncommitted changes in your checkout of that branch, nor with a conflict: then it says why and leaves the commands. "And push" pushes the branch afterwards (never forced). Crew's agents still can't merge or push themselves. A finished task you've looked at can also be merged with the Merge into main button in its dialog (or Merge and push), the same way.

Notifications. When a plan is ready for approval, or a task is ready to merge, finished with problems, blocked or failed, you get a notification: from the Mac app (Settings → Notifications → "When a Crew task needs you or has finished") and on every device that turned notifications on in the dashboard. Clicking it opens that task.

Waiting for another task. When a task needs another crew task's work first (say, an Android port of a change a Mac task is making), the Master sees which crew tasks aren't merged yet and can make the plan wait for one; you can also just say so in the task. The plan shows what it waits for and why. Once approved, the task shows as Waiting for another task and starts by itself when that one has finished. It doesn't need to be merged first: its agents are told the branch that holds that work and read it from there (or the local branch it was merged into, which may not be pushed yet). Start without waiting (or sparehand crew no-wait ID) starts it now instead. If the other task is removed before its work was merged, the waiting one stops and says so.

Blocked. When a part can't be done yet because something it needs isn't there (say, a change in another repository that isn't merged yet), its agent stops without guessing and the part shows as Blocked, saying what it waits for. The parts after it wait too, and nothing is offered for merging. Once that's ready, Resume (or Try again on the part, sparehand crew retry ID PART) carries on with the same plan: it first brings in what was merged into the base branch since the task started (when what it waited for is in the same repository), and the agent gets what the earlier attempt found. A part that went through with no changes at all can be tried again the same way.

From the terminal

Start a task with sparehand crew "TASK" [--repo PATH] [--base BRANCH] [--title TITLE]. The repository defaults to the git repository you're in. --base picks the branch to start from; by default it uses that repository's current branch. The command prints the task's id and the dashboard link (http://127.0.0.1:8730/#crew with the default port).

For example, start a task, check its plan, then approve it when it's ready. Replace ID with the id printed by the first command:

sparehand crew "Add tests for the settings page"
sparehand crew list
sparehand crew show ID
sparehand crew approve ID

list shows recent tasks: id, status, repository and task. show ID prints the plan, each part's status and agent, and the Master's final summary once there is one. approve ID approves a plan waiting for approval (review-plan). To leave parts out or ask for a new plan, use the dashboard.

The rest of what the dashboard does works from the terminal too:

sparehand crew wait ID --until plan     # returns when the plan is ready (or the task failed)
sparehand crew assign ID PART AGENT     # change a part's agent before approving
sparehand crew wait ID                  # returns when the task has finished; exit 1 if it didn't succeed
sparehand crew retry ID PART [AGENT]    # try a part that didn't make it (or was blocked) again
sparehand crew stop ID                  # and: resume ID
sparehand crew no-wait ID               # a task waiting for another one: start it now
sparehand crew mark-done ID             # you merged it yourself: stop showing it as unfinished
sparehand crew delete ID                # removes the task; its Master log is kept in the archive folder
sparehand crew ask "QUESTION"           # for an agent working on a part: ask the Master (see The Master)

wait takes --timeout SECONDS (exit code 2 when it runs out). --title names the task; without it the Master names it, and the name is used for the branch.

The dashboard must be running on this computer. The command talks to 127.0.0.1, using the port from app.json (8730 by default). If the dashboard isn't running, the command says so and exits with status 1. API errors are printed and also exit with status 1.

Commits, names and what's left over

• Parts running side by side. When a part finishes after other parts were merged, Crew first merges the crew branch into it (its agent is done by then, so nothing is touched mid-edit). Its check and the review then see the work together, and its review still shows only its own changes. If that merge conflicts, the part is left as it was and the conflict is handled when the part itself is merged.
• Agent names in commits. By default each part's commit subject ends in the agent's name, like Add settings tests (Codex). For a repository that doesn't want that in its history, set Agent names in commits (next to the review rounds) to In a trailer (a Crew-Agent: line) or Nowhere. Commits are made as Sparehand Crew and aren't signed; when a task is done the dashboard also shows a command that squash-merges the branch into one commit with a clean message, which you then sign as usual.
• A title. Give a task a title when you start it (the Title field, or --title), or leave it out and the Master names it; the branch name comes from the title.
• Parts that need your eyes. The Master marks a part Needs a manual check when it plans it as something no agent can verify here (an Android or iOS screen, how something looks). In its final review it decides again: when the part's check (or one it runs) really covered it, say iOS tests that run the new screen, it shows Verified by the Master with how, and no longer holds up merging. Otherwise the final summary says the work isn't fully verified and lists what to look at. On a finished task, Ask the Master on the part has it read that part's changes and checks again (it may run some) and either count it as verified or say what to look at; once you have looked, I checked it clears it.
• Finished tasks. A finished task lets go of its branch, so you can check it out or add a worktree for it. Mark done (merged elsewhere) turns a task you merged by hand into a finished one. Removing a task deletes its worktrees and logs but keeps the Master's log and the event record in ~/.local/state/sparehand/crew/archive/ID.

The Master

The Master is always a Claude account or the Claude API, running Claude Opus or Claude Fable. You choose it under the agent list. It plans, reviews and resolves conflicts; it doesn't do the parts itself. (Its account can still do parts as an agent too.)

Agents can ask it questions. While an agent works on a part, it can stop and ask the Master with sparehand crew ask "QUESTION", say when the brief can be read two ways, when its change has to fit another part, or when it's stuck after two tries. The Master answers in a few sentences, with the whole plan in view (which the agent doesn't have), reading files but changing nothing, and the agent carries on. Each question and answer shows in the part's events, and the review of the part is told what the Master advised. Questions to the Master per part (next to the review rounds) caps how many an agent may ask: 3 by default, None to turn it off. A question costs far less than a review, and a good answer early often saves a round of sending the part back. Parts in the cloud can't ask, since they can't reach this computer.

Your Claude usage

The Master runs on your Claude subscription, and so do Claude agents. Every review re-reads the code and the diff, so on a small task the Master can use as much as the agent doing the work. Two settings under the agent list keep this down. Both are on by default:

• Reviews of each part on Claude Sonnet. The Master still plans and does the final review on Opus or Fable; reviewing single parts runs on Sonnet. You can switch reviews to Opus or Fable.
• Save my Claude usage. The Master gives parts to ChatGPT, Gemini, Kimi or local models first, and to a Claude agent only when a part clearly needs it. The plan says which parts went to Claude and why.

Each task shows a Usage table: what the Master's planning, reviews and final review used, and what each agent used. For Claude it splits new input, cached reads (which count for much less) and output, with the API price for comparison. Codex and Gemini report one total. The task list shows each task's Claude total. Crew pays off most on bigger tasks; for a quick change, one ordinary session is cheaper. Setting Claude agents to Sonnet rather than Opus also helps a lot. Agents' questions to the Master run on the Master's model and show as Agents' questions in the table; lower Questions to the Master per part if they add up.

Adding agents

Use Add an agent… and pick where it comes from. Each agent runs its provider's own command-line tool, signed in the way that tool signs in. Sparehand never takes tokens from one tool to use in another.

Test sends a one-word request, so you know the agent is installed, signed in and answering. For an API agent (Kimi, other APIs) it first asks the provider whether the key is accepted and the model exists, and says which it is.

Choosing the model of an API agent: in Edit, press Show the models this key can use and pick one (a saved agent shows them straight away). You can also type a name.

Kimi comes as two services with different keys. A key from the Kimi Code Console (with a Kimi membership) works only with Kimi Code; a key from platform.moonshot.ai (pay-per-use) works only with Kimi API (Moonshot). If Test says the key belongs to the other service, press Edit and change Service; the saved key stays.

Every card shows its last test: "✓ Test passed" in green, "✗ Test failed" in red with the reason, or "Not tested yet". Test all (next to Add an agent) tests every switched-on agent at once. An agent whose last test failed gets no parts until a test passes or you change it in Edit. A test that runs into the agent's usage limit flags it the same way a part does ("Usage limit: back at …"), and a test that gets an answer again lifts the flag.

Usage limits. Claude and ChatGPT (Codex) agents show how much of their plan's limits is used: the 5-hour window and the week, with the time each resets when you point at the number. The bars come from the last test or part the agent ran, so press Test to bring them up to date. Above 75% the card says the agent is near its limit. A Claude agent's card also names its plan (Pro, Max 5x, Max 20x) and the day the subscription renews next: Claude Code records when the subscription started, and a monthly plan renews on that day each month (a yearly plan renews on its anniversary instead; the exact date is in claude.ai → Settings → Billing). Cloud agents share the bars of the Claude account signed in the same way (the card says whose bars they are): cloud sessions run on that same plan, so they are not a separate allowance. Cloud credits, if you have them, are a separate figure that you enter by hand. Kimi agents are asked with their key: Kimi API (Moonshot) shows the account's balance (and how much of it is a voucher), its token quota and its rate limits, and warns when the balance is under 1; Kimi Code shows the membership's windows. Claude API agents show the key's limits per minute (requests, input and output tokens), with a bar only while a minute is busy, and what the agent cost through Crew this month. Only a real request reports those limits, so Crew sends a one-token one to Claude Haiku (about a thousandth of a cent) on Test and at most every 10 minutes after the agent works. An API key can't read the account's credit balance, so you can copy it from console.anthropic.com → Billing into Edit → Credit balance: the card then shows about how much is left, counted down by what Crew spends after the day you entered it (other use of the key isn't counted, so update it now and then). It turns orange under $5, and a part refused because the credit ran out goes to another agent. Cloud agents work the same way for your cloud session credits: Claude Code doesn't report them, so copy the amount and the day they expire from claude.ai → Settings → Usage into Edit → Cloud credits. The card shows them as entered, turns orange in the last week before they expire and red once they have. Gemini, local models and other APIs don't report their limits, so their cards have no bars.

When an agent runs out mid-part. Nothing is lost. If a paid agent's usage or credit runs out while it works on a part, Crew rests that agent (until its window resets, or for a while) and gives the part to another agent. Whatever the first agent had already changed stays in the part's checkout, and the next agent is told so and finishes from there. The part's earlier review rounds and its branch carry over.

Cost at plan approval. A plan waiting for approval shows about what each part will cost, at API prices, from what that agent's parts cost in earlier tasks (with their review rounds). The estimate on What this task may do adds these up for the agents billed per use (the Claude API, Kimi, Moonshot), with what planning has cost already and the Master's reviews when the Master is the Claude API. An agent billed per use with no history is guessed from its list price (about 400k tokens in and 25k out for a part, 80k and 4k for a review); "How it's guessed" says so. A subscription (a Claude account, ChatGPT, Antigravity, a cloud session) and a local model cost nothing per task and are left out; an API with no known price is named as such. When an agent's balance (a Claude API credit you entered, or a Kimi balance in dollars) won't cover its parts, the plan shows a warning, and sparehand crew show prints it. The Master sees the same figures when it plans, so it avoids giving several parts to an agent that is nearly out.

A cap per task

Spend at most $X on this task, in the approval step, caps what the task's agents billed per use may spend, counted at the providers' list prices as their tools report the tokens. It starts at the default from Crew's settings (How the Master works → Spend at most, per task, taskCapUsd in crew.json; 0 means no cap) and you can change it for each plan. Subscriptions and local models don't count towards it.

The cap is checked each time a part (or its next review round) is about to start. Once the task has spent it, no new part starts; parts already under way finish (their work is paid for), and then the task stops and shows as Stopped at the cap, with a notification on your devices. Raise the cap and resume asks for a higher one (or 0 for none) and carries on where it stopped; a cap at or below what it has spent is refused. From the terminal: sparehand crew approve ID --cap 5 and sparehand crew resume ID --cap 10. A member's task is paid in credits and stops on its credits instead (For members), so it has no cap of its own.

A second Claude or ChatGPT account gets its own sign-in folder. When you add one, Crew picks the folder from its name (such as ~/.claude-work or ~/.codex-personal), makes it (readable only by you), and offers to open Terminal on the hub to sign in. Afterwards, if a Test fails (say the login expired), a Sign in button appears on the agent's card and opens it again. Terminal starts in an empty folder of Sparehand's own, so Claude Code doesn't get access to your home folder. If Claude Code ever asks whether to trust your home folder, answer no. You can also sign in by hand:

mkdir -p ~/.local/state/sparehand/crew/sign-in && cd ~/.local/state/sparehand/crew/sign-in && CLAUDE_CONFIG_DIR=~/.claude-work claude

mkdir -p ~/.local/state/sparehand/crew/sign-in && cd ~/.local/state/sparehand/crew/sign-in && CODEX_HOME=~/.codex-personal codex login

Check that your plans' terms allow using more than one account this way.

The Claude API runs the full Claude Code with your API key, in a sign-in folder of its own under the dashboard's state folder, so the key and your Claude subscription login never mix. It is billed per token; each task's usage records what it cost. Save my Claude usage is about subscriptions, so it doesn't hold Claude API agents back.

API keys go to the macOS Keychain (service sparehand-crew), never into a file. On a hub that isn't a Mac, set SPAREHAND_CREW_KEY_<ID> in the dashboard's environment instead.

Good at is a hint for the Master, such as "front-end" or "tests and docs". The Master already gives local models only small, clearly described parts. While Good at is empty, every agent uses a built-in hint for its model, shown in italics on its card and under the field in Edit: Opus and Fable get the hardest parts, Sonnet most coding work, Haiku small parts, Codex focused coding from a clear brief, Gemini reading and reviewing across many files (Flash: fast reading and simple edits), Kimi K3 long-context work, the highspeed models quick edits, and local models small one-file parts. Write your own to replace it. Parts at a time says how many parts an agent may work on at once (up to 4, or up to 10 for the cloud).

For members

People you add as members on the People tab (credits.md) get the Crew tab too, when Crew is on, and run tasks of their own on their prepaid credits, once you have turned members' agents on: "membersAgents": true in app.json. It is off by default, because agents run as your own user on the hub (below): with it off, a member's Crew tab says so, a task of theirs is refused before anything is set up, and a task left from before can only be stopped, ticked off or removed. The same switch decides whether a Crew agent may be the Director of a member's Studio production (studio.md). The People tab says which way it is set. What members see and get with it on:

• Their own tasks only. Every task records who started it. A member sees, approves, steers, stops, retries, merges and removes only theirs; you see all of them, each with the person's name and what it has used.
• A workspace of their own. A member's repositories live on the hub in ~/.local/state/sparehand/people/ID/repos/, and a task's checkouts under its .crew/ folder there. A repository is cloned from a Git address they give (https:// only, public or with a token of their own in the address; none of your git settings, credential helpers or SSH keys are used, so nothing private of yours can be fetched that way), or made new and empty. For each task they pick one of theirs by name: no folder browser, no paths on the hub, and a repository outside their workspace is refused.
• Agents billed per use only. Their parts go to agents with an API key of their own (the Claude API, Kimi, the Gemini CLI with a key, an Other API agent once you have priced it) or to local models through the AI hub. The Master is the cheapest Claude API agent you have set up (by its model's price); it plans, reviews and does the final review on that model, whatever Master and models your own tasks use. Your Claude accounts, ChatGPT and Antigravity are never used for a member's task, whatever the plan says or the settings are (their terms don't allow it): a part the Master gives to one goes to an agent billed per use instead, and when none is set up the task is refused with a message saying so. The member's cards show what each agent's tokens cost them.
• No settings. Members can't add, test or change agents, or how the Master works: they get your review rounds and questions per part, and every plan waits for their approval. Nothing of theirs is pushed anywhere: Merge into main puts the finished branch onto the base branch of their repository on the hub, Merge and push isn't offered, and "When a task is ready" doesn't merge their tasks by itself. Their tasks send no notifications to your devices.
• Charged per call. Every call an agent or the Master makes is charged as soon as its tool reports the tokens: your price for that provider and model (prices.tokens in app.json, cents per million tokens in and out; local models at the AI chat rate, by the model's size) times the markup, at least prices.minimum. The task shows what it has used, call by call, in its Usage table, and each charge in the ledger says which step it was for.
• An estimate held while it runs. When a task starts (and again when it resumes) an estimate is held: the average of their last five tasks (in that repository first) plus a fifth, else a credit per tracked file, and at least prices.crew.floor (100 credits by default). After each call the hold is set to what is left of the estimate; while the plan waits for approval, and when the task ends, the hold is given back.
• A clean stop. Before each part, the hold and the balance must cover about what a part costs in this task (the parts so far, else the estimate spread over the parts). When they don't, the task stops before that part, says why, and keeps everything done so far; Resume carries on with a new hold once you have added credits. Starting, approving, resuming and retrying need a balance above zero.

Agents run as the hub's own user, so a member's agents can reach whatever that user can on the hub computer, not only the member's workspace: that is why members' agents are off until you set "membersAgents": true, and why you should do that only for people you would trust with your hub account. Members never see the agents' settings: not a sign-in folder, not an API address, and not your markup (their cards show what each agent's tokens cost them). See Credits for the prices and the ledger.

Parts in the cloud

A Claude Code cloud session doesn't need one of your computers, so with a cloud agent a big task can run more parts at once than you have machines. Add one with Add an agent… → Claude Code in the cloud. It is off until you add it. Parts at a time is how many cloud sessions may run at once (4 by default, up to 10). Wait for a session's branch is how long Crew waits for one (two hours by default). The Master can give a cloud agent any part, like any other agent; you can also give it parts when you approve the plan.

For a part in the cloud, Crew:

1. Pushes the part's branch (crew/…--PART, which holds the crew branch with the parts merged so far) to the repository's origin. A cloud session starts from the pushed commit of the checkout's branch.
2. Starts a cloud session with claude --cloud, in the part's checkout, with the part's brief and the same rules the other agents get. It also tells the session to finish on its own, commit, and push once to a branch named by Crew: claude/crew-RUN-PART-N. When the repository's AGENTS.md is private to your computer (see below), its text goes along too. Claude Code only starts cloud sessions from a terminal, so this runs inside script, as for sessions in the cloud.
3. Waits for the branch. Every minute it looks on origin for that branch. A session sometimes picks its own claude/… name, so Crew also takes a new claude/… branch that builds on the part's start and whose commits say Crew-Part: claude/crew-RUN-PART-N (or the only new one, while no other cloud part of the task is waiting). It takes the branch once two looks in a row find the same commit, so the session has finished pushing.
4. Fetches it into the part's branch. Then the part goes through the usual check, the Master's review, and the merge. The commit messages are the session's summary for the Master.

The Crew tab shows each cloud part's claude.ai link and where it is: starting the cloud session, waiting for its branch, or branch back. sparehand crew show ID prints the link too.

A cloud session can't be followed turn by turn or answered from Crew. Claude Code can't drive a cloud session headless, so Crew can't see its turns, send it messages or answer its questions. The part's log says so, with the session's address. Follow it, and answer it if it asks, on claude.ai or in the Claude app. The prompt tells the session not to ask and to finish on its own, so give cloud agents self-contained parts with a complete brief.

Sent back. When the Master sends a cloud part back, the old session can't get messages. So a new cloud session starts from the part's branch as it is now (with the first session's work in it), with the Master's notes. Each round's session stays linked on the part.

When no branch comes back in time, the part fails, saying so with the session's address: it may still be working there. Try again first looks for that session's branch once more, and takes it if it has come back since; otherwise it starts a new session. You can also give the part to another agent.

Stop stops Crew from waiting, but not the session: it keeps working in the cloud. Resume goes back to waiting for the same session's branch, and so does a dashboard restart.

What is pushed. For a cloud part, the part's branch crew/…--PART is pushed to origin. Crew deletes it again there once the part is merged, or when you remove the task. The session's own claude/… branch stays on origin; delete it when you no longer want it. The crew branch itself is never pushed. Cloud sessions use your Claude subscription, like Claude agents.

What agents may do

• A working agent may read, edit and run commands in its own worktree. It may not commit, push, merge, switch branches or change remotes; Sparehand commits its changes when it finishes. Codex runs in its workspace-write sandbox.
• A cloud session works on its own copy of the repository, under claude.ai's rules. Crew tells it to push only its own claude/crew-… branch, and not to merge or open a pull request. Its work counts only once the Master has reviewed it.
• The Master plans and reviews with read-only tools. It can edit files only to resolve a merge conflict.
• Task text, code and other agents' output are given to the Master and agents as information, not as instructions.

Files

• ~/.config/sparehand/crew.json: the Master, the agents and the options (no secrets; mode 600). Each agent may also have a bin, a path to its tool, set in this file only.
• ~/.local/state/sparehand/crew/runs/ID.json: one task's plan, its parts, the reviews and what happened.
• ~/.local/state/sparehand/crew/runs/ID/: its worktrees and the logs (one per part, plus the Master's), which you can read in the dashboard, and in files/ the files you attached (readable by you only). Claude and Antigravity agents get that folder through --add-dir, the Gemini CLI through --include-directories; Codex reads it by path and gets the pictures with --image.

Remove on a task deletes its worktrees and logs; the crew/… branch stays in the repository. To switch Crew off, put "crew": false in app.json.

Checks and your repository's own instructions

What Crew learns

A part the Master sends back is a mistake made once; Crew makes sure it isn't made again. When a review shows something agents keep getting wrong in a repository, or something every brief there should say, the Master writes it down as a one-sentence lesson, and its final review looks back at the whole task (parts sent back and why, failed checks, merge conflicts, briefs read two ways) and adds what to remember. The next task in that repository starts with those lessons: the Master plans with them, every agent gets them in its brief (cloud sessions too), and each review checks the part against them. The task's events show each lesson as it is remembered.

The final review also tells you what only you can change: a flaky or slow check, instructions missing from AGENTS.md, an agent that didn't fit its parts, a task description that was read two ways. Those come as recommendations, with a notification. Both live on the dashboard's Advisor tab, where you can add lessons yourself, forget one, and mark a recommendation done or dismiss it: advisor.md.

Checks and your repository's own instructions

The Master writes each part's check the way your repository says to run its tests. It reads AGENTS.md, CLAUDE.md, the README or CONTRIBUTING. So when a suite needs a setting or a particular machine, write that down there.

When a repository has no AGENTS.md, the Master writes one while it plans (plus a CLAUDE.md that imports it), so this task and the next start with good instructions. It is kept with the task, in Sparehand's own folder, and the agents read it from there (Claude Code gets the folder with --add-dir; the others are told where it is): nothing is written into your repository by itself. When you approve the plan, the task shows what the Master wrote, as a diff, with Add it to the repository (off by default): ticked, the two files go into your repository for this task and the next. Even then they stay on your computer: git ignores them through the repository's own .git/info/exclude (which is never committed or pushed), so the people you share the project with don't see them, and Crew copies them into every agent's checkout. A project's own committed AGENTS.md is used as it is. Checks run on a spare machine through Sparehand. A check that starts with @hub runs on the hub instead, for a suite that reaches other machines itself, such as Sparehand's own engine tests. Codex agents get network access in their sandbox, so their sparehand run reaches your machines too.