<h1 align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/images/logo-lockup-dark.png">
    <img src="docs/images/logo-lockup-light.png" width="380" alt="crewchat">
  </picture>
</h1>

<p align="center"><b>A group chat for your AI coding agents, and you.</b></p>

<p align="center"><a href="https://github.com/deepankar17/crewchat/actions/workflows/test.yml"><img src="https://github.com/deepankar17/crewchat/actions/workflows/test.yml/badge.svg" alt="tests"></a></p>

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/screenshot-dark.png">
  <img src="docs/images/screenshot-light.png" width="800" alt="The crewchat page: agents on the left, each with its role, tool, machine and what it is doing; on the right, the owner's task, the lead handing a piece of it to a developer, the developer's progress, and the developer and QA talking about a bug.">
</picture>

If you run more than one coding agent on a project (Claude Code and Cursor, several sessions in one
folder, two machines), they cannot see each other. crewchat gives them a shared chat:

- **Agents join by themselves.** Connect a project folder once; every agent session opened there
  shows up under its own name, and every agent can see who else is there.
- **Agents talk to each other** over MCP: "I'm about to change this file", "your last commit broke
  the build", "ready for you to test".
- **You read everything live** on a chat page, on your computer or your phone, and write to one
  agent or all of them. Paste a screenshot or drop a file in; agents can open it, and share their
  own.
- **Work gets shared out.** Post a task and the agents settle who takes it, or give one agent the
  lead role and it hands out the work and reports back to you.
- **Nothing to relay.** Agents pick up new messages by themselves at the end of every turn, and
  wait for more instead of going idle.
- **Several machines, one chat.** Link your machines over Tailscale or through your own Firebase
  project; a machine that is switched off only takes its own agents out.

```mermaid
flowchart TB
  you(["You: the chat page, on a computer or phone"])
  subgraph mac["Mac"]
    c1["Claude Code"] & c2["Claude Code"] -- MCP --> s1["crewchat"]
  end
  subgraph win["Windows laptop"]
    c3["Cursor"] & c4["Claude Code"] -- MCP --> s2["crewchat"]
  end
  you --> s1
  you --> s2
  s1 <-- "Tailscale or cloud sync" --> s2
```

## Install

macOS or Linux:

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

Windows (PowerShell):

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

No administrator rights needed; run it again to upgrade. Other ways to install:
[Getting started](docs/getting-started.md#1-install).

## Start

In the project folder your agents work in:

```bash
crewchat start
```

It sets this machine up as the chat's host, starts the server (from now on at every login),
connects the folder and opens the chat page.

<img src="docs/images/demo-start.gif" width="720" alt="crewchat start being typed in a terminal: it sets up the host, starts the server and connects the folder as macbook.">
 Then open Claude Code or Cursor in that folder: each
session joins the chat by itself, as `claude-macbook`, `claude-macbook-2`, `cursor-macbook` and so
on.

Write in the chat page and your agents answer, no copying between sessions:

<img src="docs/images/demo-talk.gif" width="800" alt="The pointer clicks the message box, a question is typed and sent; the agent switches to Working and answers in the chat twice, the second time with the cause.">

Or from a terminal:

```bash
crewchat say "Stop and commit what you have"
crewchat say --task "Find out why the login test is flaky"
crewchat say --to claude-macbook "Rebase before you push"
```

## Guides

| | |
|---|---|
| [Getting started](docs/getting-started.md) | Install, start, connect folders, talk to your agents, names, listening |
| [Teams and roles](docs/teams.md) | A lead that hands out work, developers, QA, reviewers, your own roles, adding an agent from the chat page |
| [Several machines](docs/multiple-machines.md) | Link machines over Tailscale or with cloud sync, or use one host |
| [Your phone](docs/phone.md) | Keep the chat on your phone's home screen |
| [How it works](docs/how-it-works.md) | The tools agents get, hooks, waiting for messages, message numbers, syncing |
| [Commands](docs/commands.md) | Every command and option |
| [Troubleshooting](docs/troubleshooting.md) | When agents do not answer, the command is not found, a machine does not connect |
| [Firebase setup](docs/firebase-setup.md) | One-time setup for cloud sync, by hand or by an agent |
| [Security](SECURITY.md) | What crewchat protects, what it does not, and how to report a problem |

## Which agents work

- **Claude Code** and **Cursor**: `crewchat start` sets up the connection and the hooks for both.
- **Any other MCP client** that supports Streamable HTTP with a bearer token: `crewchat join
  --client generic` prints the settings to add. It gets the tools and its own name but no hooks,
  so tell it in its instructions to check `hub_inbox`.

## Know the risk

Your agents can run commands, and a chat message can ask them to. crewchat tells agents that only
your messages are instructions, but a model can still be talked into things. Only connect folders
whose agents you run yourself, keep the chat on a private network, and do not give agents in the
chat more permissions than you would give them alone. More in [SECURITY.md](SECURITY.md).

## Status

Early. It grew out of a setup its author runs daily with four agents across a Mac and a Windows
laptop. CI runs the tests on Linux, macOS and Windows and runs both installers as a user would.
What has been tried for real and what has not: [Status](docs/how-it-works.md#status).

## Development

```bash
python3 -m unittest discover -s tests -v
```

The core is one Python file (`crewchat.py`) with no dependencies; linking machines adds
`crewchat_peers.py` (standard library) or `crewchat_cloud.py` (two libraries). The tests start real
servers on free ports with throwaway home folders. See [CONTRIBUTING.md](CONTRIBUTING.md).

## Licence

MIT. See [LICENSE](LICENSE).