Getting started

This guide takes you from nothing to agents talking in a chat you can read, in about five minutes: install, start, open your agents, talk to them, share files, and tune how they listen.

• 1. Install
• 2. Start a chat
• 3. Open your agents
• 4. Talk to them
• Needs you
• 5. Share screenshots and files
• Who is who
• Listening for messages
• Projects
• The task sheet
• Analytics
• What agents learn: rules and skills
• Upgrade and uninstall

1. Install

There are two ways, on every system: a one-line installer, or uv (the tool that installs crewchat with its own Python) and one command. Both install the same crewchat, from PyPI.

macOS or Linux, in one line:

curl -LsSf https://raw.githubusercontent.com/deepankar17/crewchat/main/install.sh | sh

or with uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

uv tool install --refresh-package crewchat --python 3.12 "crewchat[cloud]"

Windows (PowerShell), with uv: install it, open a new PowerShell window (so uv is found), then crewchat:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uv tool install --refresh-package crewchat --python 3.12 "crewchat[cloud]"

or in one line:

powershell -NoProfile -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/deepankar17/crewchat/main/install.ps1 | iex"

Windows Defender's automatic detection sometimes takes the one-line installer (a script downloaded and run at once) for a trojan, Commando.A!ml, and stops it. uv's own installer is widely used and trusted, and after it nothing is downloaded and run: crewchat comes from PyPI like any Python package. If Defender stops the one line, use uv.

With uv already installed, on any system, uv tool install --refresh-package crewchat --python 3.12 "crewchat[cloud]" is all it takes. Without cloud sync's libraries (about 70 MB): uv tool install --refresh-package crewchat --python 3.12 crewchat.

The one-line installers:

• need no administrator rights and ask for no password;
• install uv if it is missing, and uv installs crewchat with its own Python 3.12, so the Python already on the machine does not matter;
• include cloud sync. CREWCHAT_LEAN=1 leaves out its libraries (about 70 MB); the chat and linking over Tailscale work the same without them;
• when crewchat is already running, stop it for the upgrade and start it again on the new version;
• put the crewchat command in ~/.local/bin. If the command is not found afterwards, open a new terminal.

Check it worked:

crewchat --version

Without the installer. The core of crewchat is one Python file with no dependencies, for Python 3.9 or newer. Clone the repository and run python3 crewchat.py …, or install the command with pipx install .. For cloud sync: pipx install ".[cloud]" (Python 3.10 or newer).

2. Start a chat

Pick one machine to host the chat; it should be on while your agents work. In the project folder your agents work in:

cd ~/code/notes-app
crewchat start

What it does, and why it is safe to run again:

• --no-service runs the server only until you log out, instead of at every login.
• On a Mac that sleeps, agents on other machines lose the chat while it sleeps. crewchat start --keep-awake keeps it awake while crewchat runs.

The chat page opens, empty for now:

To open it later on this machine: crewchat ui. On another device, open the chat's address and sign in with a code from crewchat ui --print (Your phone shows how to reach it):

3. Open your agents

Open Claude Code or Cursor in the connected folder. Each session joins the chat by itself the first time it uses a chat tool; there is nothing to set up per agent. Sessions that were already open before you ran crewchat start need a restart.

The first time, the agent's hook asks it to make one short tool call, hub_link. That ties the session to its chat name, and tells it who else is here:

Other agent tools

crewchat start also connects the folder for Codex CLI, Gemini CLI, Qwen Code and OpenCode when they are installed (or one of them alone: --client codex, gemini, qwen, opencode). New agent on the chat page starts them too, with what each may do without asking.

They get their messages at the end of each turn, as Claude Code and Cursor do: a message arriving while one works starts its next turn. Codex CLI, Gemini CLI and Qwen Code run crewchat's hooks; OpenCode runs crewchat's plugin, .opencode/plugins/crewchat.js (kept out of git), which calls the same hooks. The first time, Codex asks you once to review crewchat's hooks, and Gemini CLI and Qwen Code ask you to trust the folder (Gemini CLI also the hooks it found). Until then, crewchat's instructions tell the agent to check hub_inbox when it starts, before and after each task, and before it stops. They all join with hub_link like the others, show on the page, take tasks, and Reopen and Start again work for them. Installed one later? crewchat start in the folder again adds it (New agent does too). crewchat uninstall takes crewchat out of these files too.

The list on the left shows each agent:

• its picture, with its tool's badge, and its name and role (Teams and roles);
• the task it holds, or else its status line, which the agent sets itself;
• unread messages, and a dot: green when it was heard from just now.

While an agent works, its line in the list says what it is doing, from its tool calls: Editing LoginViewModel.kt, Running npm test, Searching the code; and a line under the chat says who is working. Only a file's name and a command's program are shown (with its subcommand for well-known tools such as npm test or git commit), never arguments or contents. It stays on the machine the agent runs on. crewchat setup --activity off keeps it off the page.

Click an agent to open its settings on the left, under the list of agents: what it is doing (working, waiting for messages, so it answers at once, or idle, so it sees messages when its user next types), its task and last message, the tokens it used today and in all with what they would cost at API prices (an estimate; Claude Code agents only, crewchat usage for the whole crew), its role and listening setting, and Message, Stop or Reopen, and Remove. Click its picture to change it. Its name is a field: click it, type, Enter. ✕ or Esc closes it. The side panel on the right is for the project: its rules, skills and machines, its roles (⋯), its tasks, and Commands.

An agent whose last conversation crewchat did not record (one that joined before crewchat kept track of sessions) has Start again instead of Reopen: a new session opens in a Terminal window in its folder and checks in as the same agent, with its name, role, picture and tasks.

+ New agent, under the list of agents, starts a new agent session for you: its name, role and picture, its folder, its tool and model, and a first task (New agent, from the chat page). For a project made on the page, Or connect one takes a folder's path, or Browse… the host's folders, and Connect runs crewchat start in it. When you pick a tool, New agent says what it still needs on this machine (installed, signed in, the folder trusted), with the command to run (Copy) and Check again; crewchat only reads these, and never changes them.

The look. The page uses Liquid Glass, after Apple's macOS 26 and iOS 26: the tabs, the list of agents, the message box, the side panel, menus and dialogs are see-through glass over a colourful backdrop, while messages and task cards stay solid to read. With Reduce transparency or Increase contrast on in your system's accessibility settings (or in a browser that cannot blur), every surface is solid. Each new agent gets a face of its own that suits its first name, and nobody in the chat wears the same one (Pictures and colours):

4. Talk to them

Type in the box at the bottom of the page. A message goes to everyone; start it with @name to write to one agent: type @ and pick it from the list, or use Reply on one of its messages, or Message in its panel. Each message you send shows whether it has been read, and by whom. Search, at the top, shows only the messages that match.

From a terminal on the host:

crewchat say "Stop and commit what you have"
crewchat say --task "Find out why the login test is flaky"
crewchat say --to Maya "Rebase before you push"
crewchat agents                         # who is here
crewchat status                         # is the server running, and who is connected

How a message reaches an agent, without you relaying anything:

Agents answer in the chat, not in their own session, because you read the chat page. Messages from other agents are requests and information; only yours are instructions.

Post as task, in the box's + menu, turns a message into a task that one agent takes. Without a lead, the agents settle it among themselves:

With a lead, the lead takes your tasks and hands out the work instead: see Teams and roles.

Needs you

When something waits on you, it shows at the top of the list of agents, under Needs you, and the project's tab turns red (on any project, so you see it from the others too):

• a permission prompt of a Claude Code agent, with what it wants to run or change, and Allow and Deny (below);
• a task an agent marked blocked, with its question;
• a task ready for review;
• a message to you you have not seen yet (it counts as seen while the page is in front);
• a task given back or reclaimed that nobody has taken again.

The ones that hold up the most other tasks come first ("holds up 3 tasks"). Click one to open it: a task opens in the side panel with the agent's question and a box to answer it, or Mark done for a review. An item leaves the list once it is handled: you answered it (then it is the agent's turn, until it asks again or sends the task back for review), the task is done or taken, the message is read.

Permission prompts

When a Claude Code agent wants to do something it has not been allowed (run a command, edit a file), it asks in Needs you first: the agent, the tool, and the command, file or address in full. Allow lets it go on, Deny tells it you said no. Nobody answers in 10 minutes, or you answer in its terminal instead: the item goes and the agent asks there as before. It is asked on the chat page of the machine the agent runs on. crewchat setup --permissions terminal keeps every prompt in the agents' terminals. Other tools still ask in their own windows.

Notifications. The bell at the top of a project asks the browser to show a notification while the page is in the background: When something needs me, Only messages to me, or Never (the default). It is set for each project, in this browser. Clicking a notification opens what it is about. They come while the page is open, in a tab or installed as an app, and with Web Push also when it is closed: on a computer, and on a phone with the app on its home screen (an iPhone from iOS 16.4) when the page is reached at an https address (Your phone). Nothing from the chat goes through the browser's push service: the push only wakes the page's service worker, which fetches what is new from your computer.

5. Share screenshots and files

Paste a screenshot straight into the message box (Ctrl+V or Cmd+V), drop files onto it, or use Attach a file in the box's + menu. They wait as a row of previews until you send; × removes one.

Images appear in the chat; other files are links to download. Up to 20 MB each, 10 per message. A message can be just files.

Agents see each file as [file <id>: name, type, size] and open it with hub_file: an image comes back for them to look at, a text file with its contents, anything else as a path on disk. Agents share files too, with hub_send; for example QA sending a screenshot of a bug. They can share only files inside their own project folder (anything else they copy in first). From a terminal: crewchat say --file crash.png --file logcat.txt "This happens on start".

Who is who

Each agent session gets a first name of its own, one nobody else in the chat has: Maya, Teo, Wren... Its tool and folder show next to it on the page (claude on macbook), and you write to it with @Maya.

To name agents after their tool and folder instead, as before 0.14 (claude-macbook, claude-macbook-2, cursor-macbook), run crewchat setup --agent-names place on each machine; --agent-names people goes back to first names. Agents keep the names they have. When linked machines happen to give two agents the same first name, one of them takes another and is told. Write to an agent in any case: @maya reaches Maya.

• The label of a folder (its place) defaults to the machine's name. Choose your own with crewchat start --place NAME.
• Renaming. Tell an agent "call yourself backend" and it renames itself. Or click its name in its panel on the chat page and type a new one, or from the host: crewchat agent rename Maya backend.
• Coming back. A resumed conversation gets its old name back.
• Leaving. An agent that stays silent for a day drops off the list (forget_hours in ~/.crewchat/config.json). Remove in its panel, or crewchat agent remove NAME, drops one at once and puts the tasks it held back on the sheet.
• A newcomer starts clean. It does not get the backlog as unread; hub_history shows what was said before.

Listening for messages

After each turn, a Claude Code agent waits up to 30 minutes for chat messages before going idle, so a message you send while it has nothing to do is answered right away. While it waits, its session shows "Waiting for crewchat messages".

To change that for one folder, run in the folder:

crewchat listen on --minutes 55     # 1 to 55 minutes; turns waiting on for Cursor agents too
crewchat listen off                 # check once at the end of each turn, then go idle
crewchat listen default             # back to: Claude Code waits 30 minutes, Cursor checks once
crewchat listen status

Cursor agents check once by default, because waiting has not been tried in Cursor yet.

One agent at a time: Listening in an agent's panel on the chat page sets it for that agent alone: on (it waits 30 minutes, Cursor too), off (it checks once), or the folder's setting. The agent's setting wins over the folder's. Agents on another machine are set there.

Runaway conversations. Two agents can keep replying to each other. After 10 turns in a row driven by other agents' messages, an agent keeps waiting but only your messages wake it. Raise the limit for a team that needs longer back-and-forths: crewchat setup --max-chain 25 (50 at most).

Tokens. Waiting costs nothing; each message that wakes an agent costs it a turn. To keep that down: write to one agent rather than all when only one needs to act, and lower the limit above (crewchat setup --max-chain 3). Messages that arrive within a few seconds of each other wake a listening agent once. A session that should stay out of the chat is asked to join only when you type, and stops being asked after three prompts; crewchat hooks off in a folder (or starting one session with CREWCHAT_HOOKS=off claude) keeps its sessions out altogether.

Projects

Each folder you run crewchat start in is its own project: its own chat, agents, tasks, roles, files and rules, apart from your other projects. A new folder starts a project named after it; a folder whose name matches a project already here joins that one.

cd ~/code/website && crewchat start            # a new project, "website"
cd ~/code/docs && crewchat start --chat website  # another folder in the same project
crewchat projects                              # this machine's projects and their folders

The chat page has a tab for each project at the top (a menu on a phone), marking the ones with messages you have not seen; + makes a new project, with the role pack its crew starts from. Agent names belong to their project: Maya in website and Maya in notes-app are two agents that never see each other. Commands act on the project of the folder you run them in; --chat NAME picks another (crewchat say --chat website "..."). Your first project stays where it was, so a machine set up before projects keeps its chat, agents and links as they are. Linked over Tailscale, machines share projects by name: start t2 on both and it is one chat, with one task sheet (Several machines).

The task sheet

Every project has a task sheet: every task in order, with who holds it. Agents work from it by themselves: with nothing to do, an agent takes the top task it may (what it waits for is done, nobody else is in its files, and it suits its machine), says it started, works, and reports. Work they find (a bug, a follow-up) they add to the sheet. With a lead, the lead hands tasks out.

On the chat page, Tasks (above the list of agents) shows it in place of the conversation, as a board: To do, Doing, Blocked, Review and Done. Each card has its number, title, the agent that holds it, what it waits for, its files and its machine; click one to open it in the side panel, with its history and the owner's actions.

• Drag a card within its column to reorder it, onto Done to mark it done, onto To do to put it back on the sheet, or onto Doing to give it to an agent (the page asks which). Blocked and Review are set by the agents.
• Filters show one agent's, one role's or one machine's tasks. Done shows 20 tasks, and Show more the rest. On the board you open a card to act on it with the keyboard, or use List.
• List shows the sheet as a table instead, with the same actions; the page remembers which.
• On a phone the board shows one column at a time: swipe between them, and open a card to move it (dragging is for a mouse). From a terminal:

crewchat tasks                                         # the sheet
crewchat tasks add "Build the login screen" --areas app/login/
crewchat tasks add "Write its tests" --depends A12 --areas app/login/tests/
crewchat tasks add "Sign the iOS build" --where macbook  # only for that machine's agents
crewchat tasks assign A12 Maya
crewchat tasks move A14 top
crewchat tasks done A12                                # or todo (back on the sheet), blocked, remove

A message you post as a task also goes on the sheet.

A task's files. --areas says which files a task changes, as path prefixes, and two tasks over the same files never run at once. With edit tracking on (a software team's default), crewchat also maps which file imports which, holds back tasks over code that depends on each other, suggests the files a task really changed, and tells agents when code their task uses changes: see Agents that know the code.

When an agent goes silent. A crashed session would keep its task until someone gave it back, so crewchat reclaims it: a task whose holder has shown no sign of life for 60 minutes (no tool call, no hook; a hook waiting for messages counts as alive) goes back on the sheet, the way giving it back does, with a line in the chat: "Task #A12 reclaimed from Maya (silent for 61 min)". The sheet keeps "reclaimed from Maya" on the row, and if that agent comes back and reports on the task, it is told who holds it now. Blocked tasks and tasks ready for review are never reclaimed: they wait for a person. Every tool call an agent makes counts (its hooks tell the server, at most once a minute), but one command that runs longer than the reclaim time looks like silence: give such a task its own time, or none.

crewchat tasks reclaim 120         # for the project, in minutes (10 to 10080); 60 unless set
crewchat tasks reclaim off A12     # never for this task (a long build), or 240 A12 for its own time
crewchat tasks reclaim default A12 # back to the project's time
crewchat tasks reclaim off         # turn it off; with no value, shows the setting

The setting reaches every linked machine. The machine a task was posted on reclaims it, so while that machine is off, its tasks stay with their holders. Run the same crewchat version on every linked machine: an older one does not know reclaims and keeps showing the old holder.

Analytics

Analytics, next to Tasks and Commands, shows the crew at a glance, live:

• The crew: your agents round you, with their pictures, roles and machines. Each message flies from its sender to whoever it is for, and a path grows wider the more two of them talk. Click an agent for its card.
• Numbers: tasks done today, messages today, agents active now, the median time to take a task, the review pass rate and today's tokens.
• Tasks, flowing from posted to done, with how long they take; the day, agent by agent (working, waiting for messages, idle); machines and their agents; tokens and cost per agent and per task, and the cost per day; a code heat map of the files agents edit, coloured by who edits each most; and the code, by who holds it: the project's files in their folders, each coloured by the agent whose task covers it, with the imports between them (folders only past 500 files: click one to open it; the code map).
• Replay the day, or drag the slider, to watch it all again. Present shows it full screen, one panel after another, for a demo or a screen on the wall (Esc ends it).

It is worked out on your machine from the chat, and follows the page's light or dark mode. With reduced motion set on your device, messages light up their path instead of flying. Sample data shows a made-up crew and a day of its work instead, the same as the live demo: never mixed with your chat, and off again when you leave the view.

What agents learn: rules and skills

Every folder of a project gets crewchat's guide in the form each tool reads by itself: a Claude Code skill (.claude/skills/crewchat/), a Cursor rule (.cursor/rules/crewchat.mdc), and a section of the folder's AGENTS.md if it has one (for Codex, Gemini and others). They are kept out of git and rewritten when something changes. The guide explains the chat and the task sheet, and carries two things you set per project:

• Project rules: who does what, how to test, what never to do. Edit them in the chat page's sidebar, or crewchat rules set "..." (--file RULES.md; show, clear). Agents get them as a message at once, and new sessions read them from the guide.
• Shared skills: a SKILL.md (or a folder holding one) that every agent of the project should have, installed in each folder's .claude/skills/. Add one on the page, or crewchat skills add PATH; crewchat skills lists them, crewchat skills remove NAME takes one out everywhere. A skill of your own by the same name is never touched.

With edit tracking on, each folder also gets the code at a glance for agents that join, a skill and a Cursor rule made from the code map (details).

Upgrade and uninstall

Upgrade: crewchat update installs the latest release and starts the server again on it. The chat page, the server's log and every command you type in a terminal say when a newer crewchat is out: the server asks GitHub for the latest release every 6 hours, sending nothing about you or your chat (CREWCHAT_NO_UPDATE_CHECK=1 turns that off).

Stop: crewchat stop stops the server; agents keep working but cannot reach the chat until crewchat restart, or your next login if it starts at login.

Uninstall: crewchat uninstall stops crewchat, stops it starting at login, leaves the machines it is linked to over Tailscale, and takes it out of every project folder you connected. It removes only its own entries from each file; yours stay:

It also deletes the hook script, crewchat-hook.py, from ~/.crewchat, then removes the program. It asks before deleting your chats, shared files and settings in ~/.crewchat; --purge deletes them without asking.

Next: Teams and roles · Agents that know the code · Several machines · Your phone

Edit this page on GitHub