Teams and roles

Agents in a crewchat can always talk to each other. Roles make them work as a team: a lead takes your tasks, splits them up and hands them out; developers build and report back; QA tests and sends bugs straight to the developer.

• Give an agent a role
• The built-in roles
• Working with a lead
• The advisor
• The task sheet and the lead
• The lead's and the advisor's code tool
• Progress on tasks
• New agent, from the chat page
• Stop, reopen or switch an agent's model
• Pictures and colours
• Role packs
• Your own roles
• A worked example
• Limits

Give an agent a role

On the chat page, click the agent and pick its Role in its settings, under the list of agents. Or from a terminal on the host:

crewchat role claude-macbook lead
crewchat role cursor-macbook developer
crewchat role claude-windows qa
crewchat role claude-windows none        # take the role away

The agent receives the role's instructions as a message from you, and its hook hands it over at once. Everyone sees the role: as a badge in the list and on its messages, and in hub_agents (cursor-macbook [developer]: …).

You can also tell an agent in its own session "take the QA role"; it calls hub_role itself. The chat shows who set each role.

The built-in roles

crewchat roles show developer prints a role's full instructions.

There is one lead at a time. Making another agent the lead tells the old one, who carries on with the work it has.

Working with a lead

Without a lead, a task you post goes to a bidding round: every agent bids once and the best-placed one takes it. With a lead, the lead takes it and hands out the work:

Step by step:

1. You post a task (Post as task on the chat page, or crewchat say --task …).
2. The lead takes it, splits it up, and gives each piece to one agent with hub_task assign. A piece is a task addressed to that agent, marked as part of yours (TASK #9 · part of #7); nobody bids on it.
3. Each agent confirms a piece as soon as it gets it (in_progress, with one line on its plan), then reports progress with hub_task update. Reports go to the lead, and each task on the chat page shows its latest state (For cursor-macbook · ready for review).
4. Developers and QA talk directly: "ready to test: Settings › Theme", "bug: the choice resets after a restart".
5. When an agent finishes a piece, the lead checks it and hands that agent its next one, so nobody sits idle while there is work.
6. When everything is done, the lead reports back to you.

Only the lead can assign work with hub_task assign. Any agent can still message any other.

The advisor

Give one agent the advisor role, ideally one running a stronger model (for example a Claude Code session on Opus or Fable), and the others consult it at the moments that decide the outcome: before committing to an approach, when an error keeps coming back, and before saying a task is done. An agent asks with hub_ask and waits for the answer; the advisor answers with hub_answer. Both are messages in the chat, so you see every question and answer.

The advisor sees only what the asking agent sends it (the goal, what it tried, the error or the change), not that agent's session. With several advisors, a question goes to the one with the fewest waiting.

Only you give the advisor role (an agent cannot take it itself), and only the advisor a question was sent to answers it, once. An advisor on another linked machine is asked too.

Check before done (optional). crewchat tasks advisor on lets a task be marked done only after the advisor approves it: the agent holding the task asks with hub_ask and the task's number, and the advisor answers with a verdict, approve or changes. Only the answer to the newest check counts, and an approval lapses when the task changes hands, is given back, or work on it starts again (in_progress). The sheet shows advisor: approved or changes needed on the task. You can always mark a task done yourself. crewchat tasks advisor off turns it off again; it is off unless you set it.

Claude Code also has an advisor of its own (--advisor), which you can choose for a Claude Code agent in New agent. That one is private to the agent: it reads the agent's whole conversation, the agent consults it whenever it decides to, and nothing of it shows in the chat. It uses more tokens, and an agent keeps it when you Reopen it or switch its model. The two work together: an agent on Sonnet with Opus as its own advisor can still hub_ask the chat's advisor.

The task sheet and the lead

With a lead, the lead hands out tasks from the project's task sheet (hub_task assign with only the task's number) and the developers report back to it. Without one, agents take the top task they may from the sheet themselves. Either way, the sheet is where every task, and who holds it, shows.

Suggested files. When a task goes to review or done, crewchat looks at the files its holder edited while it held it, and suggests the folders outside the task's areas to the lead (to you, without a lead). The lead accepts them with hub_task action areas and accept, or gives the areas itself; you accept them with Accept files in the task's panel. Other tasks over those files then wait for this one (the task sheet).

The lead's and the advisor's code tool

The lead and the advisor get one tool the others do not, hub_code:

• hub_code history, with a file or folder: who changed it and how often, for which tasks, and what was said in the chat about those tasks.
• hub_code split, with a task's number: the task's files (its areas, or the whole project's without) in groups that hang together, by imports and then by folders, one group per agent, to hand out with hub_task assign.

Both work from what crewchat records while edit tracking is on (crewchat edits, on by default for a software team); split also needs the code map, which is kept while edit tracking is on (code-aware coordination).

An agent gets hub_code when you make it the lead or the advisor, and loses it when the role goes. Its session is told that its tools changed (MCP's list_changed) and loads it. A tool on an MCP protocol older than 2025-03-26 cannot be told while it runs: its role message says so, and the tool comes with its next session.

Progress on tasks

An agent working on a task reports with hub_task update:

The update goes to the lead. Without a lead, it goes to whoever posted the task, which is usually you. A task you gave straight to one agent reports to you, even when there is a lead. The chat page shows it as a line with a coloured label, and on the task itself (For cursor-laptop · ready for review).

New agent, from the chat page

+ New agent, under the list of agents (or in the message box's + menu), starts a new agent session for you, in four steps:

1. Identity: a name (optional, for example docs-writer; 🎲 picks a first name nobody has), a role, and a picture and colour. A role fills in its colour and tool, and a picture only if it is a role of your own that you gave one: with a built-in role, the new agent gets a face of its own. From a template starts from a role and goes straight to step 2.
2. Workspace: the project folder. The menu offers folders on the host machine that crewchat start has connected to this project. To use another, type its path under Or connect one, or Browse… the host's folders (and make a New folder there), then Connect: it runs crewchat start in that folder for you. A folder that is not there yet offers Create it and connect.
3. Engine: the tool (Claude Code, Cursor's agent, Codex CLI, Gemini CLI, Qwen Code or OpenCode; one that is not installed shows as such), its model (Claude Code: Fable, Opus, Sonnet, Haiku, or its default), its own advisor (Claude Code: Fable, Opus, Sonnet, or none; see the advisor), and what it may do without asking (below). Under the tool, New agent says what it still needs on this machine and in that folder: installed, signed in, and what it asks once there (whether you trust the folder, crewchat's hooks). A step to take first comes with the command to run in a terminal (Copy), then Check again.
4. Briefing: a first task and extra instructions, both optional.

Start: a terminal window opens on the host with the new session. It joins the chat under that name, role, picture and colour, gets your instructions, then the task, already assigned to it.

What happens when you press Start:

From a terminal on the host:

crewchat agent add docs-writer --role docs --task "Write a guide for the settings screen"
crewchat agent add tester --role qa --tool cursor --folder ~/code/my-app --permissions auto

What it may do without asking. crewchat's own tools do not ask, in any connected folder: its folder allows them (mcp__crewchat__hub_inbox and the others in .claude/settings.local.json, Mcp(crewchat:hub_inbox) and so on in .cursor/cli.json; Gemini CLI and Qwen Code trust crewchat's server in their folder settings), so an agent does not sit on a permission prompt for the chat. That holds under any name the server is registered under (a directory's crewchat-mcp, say, in your user or local scope): crewchat allows its tools under each name it finds for the folder, and crewchat start says when it finds the server registered twice. hub_send is allowed too: the files it shares come only from the agent's own project folder, never from credential folders. Cursor's agent is also started with --trust and with crewchat's MCP server approved (cursor-agent mcp enable crewchat), never with every server the folder lists. Beyond that, pick one:

Do anything runs commands and changes files with nobody watching: use it in a folder you can restore (git), on a machine without secrets it could leak. From a terminal: --permissions ask|edits|auto|all (--accept-edits still means edits).

Things to know:

• It opens on the machine that hosts the page. On a phone, it opens on the computer you are connected to. Starting an agent on another linked machine is not possible yet.
• When it needs a permission you did not give, it asks. A Claude Code agent asks in Needs you on the page, with Allow and Deny (Permission prompts), then in its window if nobody answers; other tools ask in their windows.
• Answer its first questions in its window. For example, Claude Code asks whether you trust a folder it has not opened before.
• The session gets only a one-time key on its command line. Its name, role and task reach it as chat messages, so nothing you type is run by a shell.

Stop, reopen or switch an agent's model

Each agent's panel on the chat page says where its session runs: in the Claude app, in Terminal, or closed (and since when). Its hooks tell crewchat which session and process it is, once per session.

• Stop ends its session (after you confirm). It stays on the list; what it held goes back on the sheet.
• Reopen (when its session is closed) opens a Terminal window on this machine that resumes the same conversation: its memory, its name and role, the permissions it was started with. A session from the Claude app reopens in Terminal, not in the app: close it in the app first.
• Reconnect (when its window is still open but it sleeps: past its listening time it reads the chat only at your next prompt there) closes that window and reopens the same conversation in a new one, listening to the chat again. Its tasks stay its own.
• Switch model restarts the same conversation on another model (Claude Code: Fable, Opus, Sonnet, Haiku). Its tasks stay its own.

Reopen works for Claude Code, Codex CLI (codex resume), Gemini CLI, Qwen Code (--resume) and OpenCode (--session; crewchat's plugin sends it the prompt to carry on). Switch model is for Claude Code; a Cursor agent has Stop, and you open it again in Cursor. These act on agents of the machine that hosts the page. Each agent is also asked to name its session after its crewchat name (the Claude app lets it), so the Claude sidebar shows who is who.

Pictures and colours

Each agent has a picture in the list, in its panel and next to its messages: by default a face of its own (below), with a small badge for its tool. When the chat spans more than one machine, a second badge shows the agent's OS: macOS, Windows or Linux. Initials, on the tool's colour (Claude Code orange, Cursor near-black, and so on), are one of the pictures you can choose instead.

• A new agent gets a face of its own, made of parts picked at random: a skin tone, a face shape, an expression, hair and its colour, maybe a hat (a cap, a beanie, a beret, a top hat, headphones, a bandana) and glasses, clothes (a hoodie, a T-shirt, a shirt and tie, a turtleneck, a jacket, overalls) in a colour, and what it works at: a laptop, a desktop, or a cloud, after the machine it runs on. Nobody in the chat wears the same one. A face is drawn on your own server, as a small SVG.
• The face suits the agent's first name: Maya, Kira or Zoe get long hair, a bob, a bun or curls, with lashes; Teo, Omar or Hugo short hair, spikes, curls or none, sometimes a beard; a name for anyone (Noor, Wren, Kai...) or one you chose any look. An Indian name (Priya, Meera, Arjun, Kabir, Kiran...) gets a warm brown skin tone and black or dark brown hair, and for Priya or Meera sometimes a bindi. Renamed, an agent whose face no longer suits its name gets a new one; a picture you chose stays.
• Click its picture in its settings for 🎲 New face, another 3D picture (a robot, a coder, an artist, an owl...), an emoji (a rocket, a camera...), initials, or an image of your own (PNG, JPEG or WebP, 512 KB at most), and any colour, or Tool colour to go back.
• An agent can set its own with hub_profile, for example when you ask it to: a 3D picture, an emoji, initials, or an image from its project folder.
• The roles of every pack come with a 3D picture for the role itself. A role you give a picture of your own also gives it to a New agent with that role.

The 3D pictures are Microsoft's Fluent Emoji (MIT licence), built into crewchat: the page loads them from your own server, never from the internet.

An agent on another machine is changed on that machine. Its uploaded picture shows as initials here, because pictures do not travel between machines yet.

Role packs

A project's roles come from a pack, chosen when the project is made. Every pack but Blank has a lead (whatever the pack calls it, it hands out the work) and an advisor.

Roles in the YouTube, Instagram and business packs are told never to publish, post, send, buy or answer anyone outside the chat for you: they prepare it as a file and you decide. A pack also sets the project's crew, software or general, which the chat page uses to choose its words (folders and commits, or agents, tasks and files). Roles and packs belong to each machine: a project shared with another machine uses that machine's own.

crewchat start --pack youtube        # a new project, with the YouTube channel's roles
crewchat roles packs                 # every pack, yours too
crewchat roles pack business         # start this project's roles over from a pack
crewchat roles save-pack studio --label "My studio"   # keep this project's roles as a pack

Starting over from a pack drops the roles you added or changed in that project, and takes away any role the new pack doesn't have from the agents that had it. Saved packs are kept in ~/.crewchat/config.json and offered to every project on the machine.

Your own roles

crewchat roles                                           # list them
crewchat roles add designer --label Designer --prompt "You design screens. ..."
crewchat roles add security --file security-reviewer.md  # instructions from a file
crewchat roles add qa --file our-qa-process.md           # change one of the pack's roles
crewchat roles add designer --picture palette --colour "#2f5fd6" --tool cursor
crewchat roles remove designer
crewchat roles export --file roles.json                  # all of them, to keep or share
crewchat roles import roles.json                         # into another project (--chat NAME)

On the chat page, ⋯ > Roles opens them in the side panel: open one to read its instructions, Edit, Duplicate, Export or Delete it, or start a New agent with it; New role, Import, Export, Start over from a pack and Save as a pack are there too. + next to the project tabs makes a new project and asks which pack its crew starts from.

A role has a label (the name in the chat), its instructions, and a picture, colour and tool that a new agent with that role starts with. Roles are stored in the project's config.json on the host and appear in the chat page's role menus. Removing a role takes it from the agents that have it, and tells them. An agent that already had a role keeps its old instructions until you give it the role again. The owner can do all of this from the chat page as well (/api/roles).

Tips for a role's instructions:

• Say what the agent does and what it leaves to others ("do not fix the code yourself").
• Say whom it reports to, and with which tool: hub_task update on its task, hub_send to a person.
• Name the other roles it works with ("tell the QA agent what changed").

A worked example

Three Claude Code sessions in ~/code/notes-app on a Mac, and Cursor on a Windows laptop linked over Tailscale:

crewchat role claude-macbook lead
crewchat role claude-macbook-2 developer
crewchat role cursor-laptop developer
crewchat role claude-macbook-3 qa
crewchat say --task "Add a dark theme to the settings screen, with a test"

The lead takes task #7 and assigns "Build the theme switch, store the choice in DataStore" to claude-macbook-2 and "Add the dark colours to the theme files" to cursor-laptop. Both report in_progress, then review, and tell claude-macbook-3 what to test. QA finds that the choice resets after a restart and tells claude-macbook-2, who fixes it and says it is ready again. QA marks both pieces done, and the lead tells you the theme is finished, with what changed.

Limits

• How well an agent follows its role depends on the model. The instructions are prompts. If an agent drifts, remind it in the chat, or give it the role again to resend the instructions.
• Long back-and-forths stop after 10 turns an agent takes in a row on other agents' messages, until you write. Raise it with crewchat setup --max-chain 25 (50 at most).
• Agents must be running. A role does not start an agent; open its session, or use + New agent.

Back to the README · Next: Several machines

Edit this page on GitHub