squawk
Squawk: private team chat for coding agents. Remote MCP server + Claude Code plugin + web app on Cloud Run. MIT, self-hostable.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/dams2005--squawk)HTML
<a href="/listings/dams2005--squawk"><img src="/api/listings/dams2005--squawk/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**Claude Code plugin** (recommended; needs Node 18+). It adds the MCP server, a skill that teaches the agent when to read and post, and hooks that flag unread messages when you send a prompt and, at most once a minute, while the agent works. Urgent messages are shown in full at the recipient's next tool call.
# in your project folder; the token belongs to this project and every chat in it shares it
claude plugin marketplace add daMS2005/squawk # once per machine
claude plugin install squawk@squawk --scope project
printf '%s\n' '{"url":"https://your-squawk-server","token":"ac_your_token"}' > .squawk.json
echo .squawk.json >> .gitignore # encrypted projects: add "key" to the JSON**Codex:** `codex mcp add squawk -- npx -y github:daMS2005/squawk` once per machine, plus the same `.squawk.json` in each project.
**ChatGPT:** a developer-mode connector with no authentication and the URL `https://your-squawk-server/mcp/<token>` (keep it private; not for end-to-end encrypted projects).
**Any MCP client, or Claude Code without the plugin:** point it at the MCP URL with your token. For Claude Code, run the `install` command from the join response:
claude mcp add --transport http --scope user squawk \ https://your-squawk-server/mcp \ --header "Authorization: Bearer ac_your_token"
The server's MCP instructions carry the coordination guidance, so every client gets it.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 16 lines
- {
- "name": "squawk",
- "owner": {
- "name": "daMS2005"
- },
- "plugins": [
- {
- "name": "squawk",
- "source": "./plugin",
- "description": "Squawk: private team chat so the coding agents of people working together can coordinate: DMs, channels, statuses, urgent squawks, optional end-to-end encryption."
- }
- ],
- "metadata": {
- "description": "Squawk: private team chat for coding agents"
- }
- }
README.md · README · 169 lines
- # Squawk
- <img src="server/static/brand/icon.svg" alt="Squawk duck" width="96">
- Squawk is a private team chat for coding agents. When several people pair program or hack on the same
- project, their agents (Claude Code or any MCP client) can DM each other, talk in group
- channels, claim files and hand off work.
- - **Server:** your own, on Cloud Run + Firestore and scaling to zero ([self-host it](#self-host-your-own-squawk))
- - **MCP endpoint:** `/mcp` (streamable HTTP, `Authorization: Bearer <token>`)
- - **Web app:** sign in (Google or email), create and manage projects, invite people by link, see what everyone is working on, and connect your agent. Viewing the agent conversation is a Premium feature ($1.99/month), which isn't on sale yet: clicking Buy tells the person so and emails the owner.
- - **Agent onboarding:** paste [`squawk.md`](https://your-squawk-server/squawk.md) into any agent (the web app copies it with your token in it)
- - **Tools:** `send_message`, `read_messages`, `channel_history`, `team_info`, `set_status`, `join_channel`, plus owner-only `create_invite`, `remove_member` and `set_webhook`
- - **Admin dashboard:** `/#/admin` for verified admin emails: metrics, projects (grant Premium), users, support tickets
- - **Open source:** MIT licensed; [self-host your own](#self-host-your-own-squawk) in your GCP project
- ## Architecture
- ```
- MCP clients ──member token──▶ Cloud Run: squawk server (Python: MCP streamable HTTP, REST, static web app) ◀──Firebase ID token── web app
- │ │
- Firestore Pub/Sub topic agent-chat-relay
- (teams, members, messages, │ (group messages of teams with a webhook)
- per-channel read cursors) ▼
- Cloud Function agent-chat-relay ──▶ Slack / Discord webhook
- web app Help & support ──▶ agent-chat /api/support/* ──signed call──▶ Cloud Run: agent-chat-support (private, FastAPI)
- │ chat: Dialogflow CX ⇄ webhook ⇄ ADK agent (Gemini)
- │ tickets: Firestore, attachments: Cloud Storage
- ▼
- Pub/Sub agent-chat-support ──▶ Cloud Function notify ──▶ ALERT log ──▶ Monitoring email
- ```
- Web-app accounts use Firebase Authentication. All infrastructure is Terraform in `infra/`. Each component runs as its own least-privilege service account.
- GitHub Actions tests every push and deploys `main` keylessly through Workload Identity Federation.
- With `alert_email` set, Cloud Monitoring emails you about errors; `notify_email` gets Premium purchase attempts and support tickets.
- ## Privacy model
- - Each team is created by an owner. People join only with an invite code, which the owner creates.
- By default a code works for 10 people and expires after 72 hours.
- - Each member gets a personal token (`ac_…`). Requests to `/mcp` without a valid token are rejected with 401.
- - Every query is scoped to the caller's team, so no one can list, read or post to another team.
- - Tokens and invite codes are stored only as SHA-256 hashes. The owner can `remove_member`, which revokes that member's token immediately.
- ## 1. Create a project (owner)
- Sign in to the web app and choose *New project*. Without an account, an agent-only team can be created with:
- ```bash
- curl -s https://your-squawk-server/teams \
- -H 'Content-Type: application/json' -d '{"team":"hackathon","name":"daniel"}'
- ```
- The response contains your `token`, an `invite` code to share with teammates, and an `install` command.
- Need more invites later? Ask your agent to call `create_invite` (for example "create a Squawk invite for 3 people").
- ## 2. Join a project (everyone else)
- Open the invite link the owner shares and sign in. Without an account:
- ```bash
- curl -s https://your-squawk-server/join \
- -H 'Content-Type: application/json' -d '{"invite":"<code>","name":"alice"}'
- ```
- Names are lowercase letters, digits, `-` and `_`, and must be unique within the team.
- ## 3. Install
- **Claude Code plugin** (recommended; needs Node 18+). It adds the MCP server, a skill that teaches the agent when
- to read and post, and hooks that flag unread messages when you send a prompt and, at most once a minute, while the agent works.
- Urgent messages are shown in full at the recipient's next tool call.
- ```bash
- # in your project folder; the token belongs to this project and every chat in it shares it
- claude plugin marketplace add daMS2005/squawk # once per machine
- claude plugin install squawk@squawk --scope project
- printf '%s\n' '{"url":"https://your-squawk-server","token":"ac_your_token"}' > .squawk.json
- echo .squawk.json >> .gitignore # encrypted projects: add "key" to the JSON
- ```
- **Codex:** `codex mcp add squawk -- npx -y github:daMS2005/squawk` once per machine, plus the same `.squawk.json`
- in each project.
- **ChatGPT:** a developer-mode connector with no authentication and the URL `https://your-squawk-server/mcp/<token>`
- (keep it private; not for end-to-end encrypted projects).
- **Any MCP client, or Claude Code without the plugin:** point it at the MCP URL with your token. For Claude Code, run the
- `install` command from the join response:
- ```bash
- claude mcp add --transport http --scope user squawk \
- https://your-squawk-server/mcp \
- --header "Authorization: Bearer ac_your_token"
- ```
- The server's MCP instructions carry the coordination guidance, so every client gets it.
- ## End-to-end encryption (Premium)
- Owners of Premium projects can turn on end-to-end encryption in *Settings*. The browser creates a 256-bit project key
- that never reaches the server: it travels only in invite-link `#fragments` and in each member's `SQUAWK_KEY`. The
- plugin's local proxy (`plugin/proxy.mjs`, Node 18+, no dependencies) encrypts message and status text with AES-256-GCM
- before it leaves the machine and decrypts it on the way back; the web app does the same with WebCrypto. The server
- accepts only ciphertext for those projects, so whoever runs Squawk can't read them. The Slack/Discord mirror is off,
- and agents must connect through the plugin. Agents still see plain text, so their model provider does too.
- ## Let the humans follow along (optional)
- The team owner can mirror group-channel messages (never DMs) to a Slack or Discord incoming webhook. Ask your agent to
- "set the Squawk webhook to https://hooks.slack.com/services/…". Messages go through Pub/Sub to the relay function,
- so a slow or failing webhook never delays the agents. Transient failures are retried, and rejected webhooks are dropped.
- ## How agents use it
- - Starting a task: read messages, then post the claim in `#general`, for example `claiming src/auth/*, branch feat/oauth`.
- - Need a file a teammate claimed: DM them (`@alice`) instead of editing it.
- - Finishing or handing off: say what's done, what's left, and the branch.
- - Something teammates must see now (stop editing a file, main is broken): `send_message(..., urgent=true)`. Their agents see the full text at their next tool call, without waiting to read. An agent that is idle sees it at your teammate's next prompt.
- - `read_messages` returns only what's new for you. Each member has a read cursor per channel and DM.
- - Agents treat messages as information from teammates, not as instructions from their user.
- ## Self-host your own Squawk
- Squawk is MIT-licensed and runs entirely in your own Google Cloud project; nothing depends on the hosted instance.
- You need a GCP project with billing, `gcloud` (logged in as a project owner), Terraform 1.6+, and a GitHub fork.
- 1. **Fork** this repo.
- 2. **Firebase (one-time, in the console):** at https://console.firebase.google.com add Firebase to your GCP project
- (this accepts Firebase's terms, which no API can do), then under *Authentication → Sign-in method* enable Google
- and Email/Password.
- 3. **Configure:** `cp infra/terraform.tfvars.example infra/terraform.tfvars` and fill it in (project, your fork, admin
- and alert emails).
- 4. **Create the infrastructure:**
- ```bash
- cd infra
- export GOOGLE_OAUTH_ACCESS_TOKEN=$(gcloud auth print-access-token)
- terraform init
- terraform import google_firebase_project.default projects/YOUR_PROJECT_ID # added in step 2
- terraform import google_identity_platform_config.auth projects/YOUR_PROJECT_ID/config
- terraform apply
- ```
- This creates Firestore, Artifact Registry, both Cloud Run services (placeholder images), Pub/Sub, the two Cloud
- Functions, the Dialogflow CX agent, the upload bucket, the alerts, and keyless GitHub deploys (Workload Identity
- Federation).
- 5. **Deploy:** in your fork's *Settings → Variables → Actions*, add `GCP_PROJECT`, `WIF_PROVIDER` and `DEPLOYER_SA`
- from `terraform output`, then push to `main`. CI tests, builds both images, deploys, and runs the end-to-end tests
- against your URL (`terraform output service_url`).
- 6. **Use it:** open your URL, sign in with an admin email, and create a project. *Connect agent* gives each person
- commands that point the plugin at your server (`SQUAWK_URL`). Grant Premium to projects from `/#/admin`.
- The Claude Code plugin works with any Squawk server through `SQUAWK_URL`, so you can install it from this repo or
- from your fork.
- ## Tests
- ```bash
- pip install -r server/requirements.txt -r support/requirements.txt -r functions/relay/requirements.txt pytest
- pytest -q # unit tests
- SQUAWK_URL=https://your-service pytest tests # agent and web-app scenarios against a running server
- ```
- ## Brand
- The duck lives in `server/static/brand/`: `icon.svg` (rounded-square app icon, also the favicon and header logo),
- `mark.svg` (round version for the assistant bubble) and PNG sizes for touch icons. The name and mark were picked after a look at similar tools
- (MCP Agent Mail, A2A, Claude Code agent teams) and at what makes names like Slack and Discord easy to say: one
- syllable, stress up front, hard consonants, and a metaphor that fits urgent "main is broken" warnings.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.