Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
   • Connect to a server
3. Usage
   • First run
   • Commands
   • Layouts
   • Two accounts on one computer
4. Privacy & Security
5. Development
6. Host your own server
7. Roadmap
8. License
9. Acknowledgments

About The Project

squad-chat puts a group chat next to your Claude Code conversation. You keep working with Claude on the left while your friends' messages come in on the right.

• Lives inside Claude Code. One /chat command opens a pane: no browser tab, no extra app.
• Never reaches Claude. What you type in the pane never enters the conversation, and slash-command arguments are hidden from the model, so chatting costs no tokens.
• Presence across rooms. See who's online in every room you share and who's typing, with a status line for unread messages and an optional toast when someone @mentions you.
• Your own server. Each group of friends runs its own free Supabase project. There is no central service and no account with us.
• Private rooms. Rooms are joined with a passcode, and the database only shows a room's messages to its members.
• Survives bad networks. After a dropped connection, a closed laptop or a crashed process, it reconnects by itself and fetches exactly the messages you missed.
• Fits any terminal. Docked beside the transcript in a wide terminal, compact above the prompt in a narrow one, and a one-line summary when the pane is closed.

It is a Claude Code mod: a plugin of function hooks, plus a small Node process that holds the connection to Supabase. docs/ARCHITECTURE.md explains how the pieces fit.

(back to top)

Built With

(back to top)

Getting Started

Prerequisites

• Claude Code 2.1.287 or newer, in the terminal. The desktop app can't start the chat's background process yet.
• Node 22 or newer on your PATH:

  node --version
  

• A server: one Supabase project per group of friends. Get its URL and key from whoever hosts it, or host one yourself.
• A terminal with truecolor, such as iTerm2, Ghostty, kitty or WezTerm.
• For the side-by-side layout: Claude Code's fullscreen layout (/tui fullscreen) and a terminal at least 110 columns wide.

[!NOTE] Claude Code decides where the pane goes, not the mod. Below 110 columns the pane opens above the prompt in a compact layout. While it's closed, a one-line summary sits above the prompt with an Open button.

Installation

The repository is its own plugin marketplace.

1. Add the marketplace and install the plugin:

   claude plugin marketplace add chrisluo5311/squad-chat
   claude plugin install squad-chat@squad-chat
   

   Or, from inside Claude Code:

   /plugin install squad-chat --marketplace chrisluo5311/squad-chat
   

2. Restart Claude Code, or run /reload-plugins.
3. Connect to a server, then open the pane with /chat.

To update later:

claude plugin marketplace update squad-chat && claude plugin update squad-chat@squad-chat

If you host your group's server, also run supabase db push again from an updated clone, so the server has what the new version needs. For example, typing indicators need 0.5.0's database change.

To uninstall:

claude plugin uninstall squad-chat@squad-chat && claude plugin marketplace remove squad-chat

To try it without installing:

git clone https://github.com/chrisluo5311/squad-chat.git
claude --plugin-dir ./squad-chat/plugins/squad-chat

Connect to a server

squad-chat has no central server. Each group of friends shares one Supabase project, its server: one person hosts it on Supabase's free plan, and everyone else connects with two values from them:

• the project URL, such as https://abcd1234.supabase.co
• the project's publishable key, sb_publishable_… (safe to share, unlike the secret key, which you never share)

Set them when you install:

claude plugin install squad-chat@squad-chat \
  --config supabase_url=https://abcd1234.supabase.co \
  --config supabase_key=sb_publishable_...

or later, from /config in Claude Code (squad-chat's options), or from a shell:

echo '{"supabase_url":"https://abcd1234.supabase.co","supabase_key":"sb_publishable_..."}' \
  | claude plugin configure squad-chat@squad-chat --values-stdin

Until a server is set, the pane says so and shows these steps.

(back to top)

Usage

First run

1. /chat opens the pane.
2. Sign in, depending on how your server is set up:
   • With a name: type the name you want and press Enter. That's it.
   • With your email: type your email and press Enter, then type the code from the email.
3. Create a room and give its name and passcode to your friends. Type this in the pane:

   /room our-team some-passcode
   

   Your friends join with the same line.
4. Chat: type in the pane and press Enter. Esc goes back to the prompt.

[!IMPORTANT] An account made with just a name can't be recovered. It has no email, so once you sign out, delete ~/.config/squad-chat or switch computers, you can't sign back into it. Signing in again makes a new account: rejoin your rooms with their passcodes and you'll see their history again. Messages from the old account stay in the rooms until they expire after 30 days. Signing in by email doesn't have this problem.

Commands

The pane's input box takes /room, /who, /name, /logout and /help too. Type passcodes there: it never touches the conversation.

Layouts

Two accounts on one computer

Each account needs its own config folder. Start the second Claude Code with:

SQUAD_CONFIG_DIR=~/.config/squad-chat-b claude

Gmail delivers you+b@gmail.com to you@gmail.com, which makes a handy second account for trying it out.

(back to top)

Privacy & Security

• What Claude sees. Nothing typed in the pane enters the conversation. The arguments of /say, /room and /chat-login are replaced with a placeholder before Claude Code stores the command, and command answers are notices the model never reads. Claude Code still keeps a slash command's raw text in one bookkeeping line of the local transcript on your own disk, so type passcodes in the pane if that matters to you.
• Who sees your messages. Only members of the room. Access is enforced in the database with row-level security, and you become a member only with the room's passcode. Five wrong passcodes lock you out for 15 minutes.
• Who runs the server. Your squad's server belongs to whoever hosts it, and they can read its database like any database admin. Pick a host you trust, or host it yourself.
• What friends see. Your display name (the name you picked, or the part of your email before the @) and whether you're online. Never your email.
• What's stored. Messages are deleted after 30 days. Your sign-in session is kept in ~/.config/squad-chat/session.json, readable only by you, and /chat-logout removes it. An account made with just a name can't be signed back into once you sign out, so /chat-logout asks twice.
• Abuse limits. At most 10 messages per 10 seconds per person, and 500 characters per message.

Found a security problem? Please report it privately, as described in SECURITY.md.

(back to top)

Development

Want to help? CONTRIBUTING.md covers setting up, the tests and how to send a pull request.

# The mod
claude plugin validate ./plugins/squad-chat   # check the manifest and hooks
claude plugin test ./plugins/squad-chat       # mod tests, against a fake bridge
claude --plugin-dir ./plugins/squad-chat      # run Claude Code with this checkout

# The bridge
cd plugins/squad-chat/bridge
npm install && npm run build                  # rebuild dist/bridge.mjs after editing src/
npm test                                      # two users, two bridges, local Supabase

# The database
supabase start                                # local stack on ports 56420-56429
supabase test db                              # pgTAP access-control tests
supabase db advisors --local --type all

To run the mod against the local stack, start Claude Code with:

SQUAD_SUPABASE_URL=http://127.0.0.1:56421 \
SQUAD_SUPABASE_KEY=<local publishable key from `supabase status`> \
SQUAD_CONFIG_DIR=$(mktemp -d) \
claude --plugin-dir ./plugins/squad-chat

Sign-in emails land in the local mail UI at http://127.0.0.1:56424.

(back to top)

Host your own server

One person per group does this, once. It fits in Supabase's free plan.

1. Create a Supabase project at supabase.com.
2. Create the tables. With the Supabase CLI, from a clone of this repository:

   supabase link --project-ref <your-project-ref>
   supabase db push
   

3. Lock down Realtime. In the dashboard, under Realtime → Settings, turn off Allow public access to channels.
4. Choose how people sign in. You can turn on either or both.
   • With a name (simplest, no email service). Under Authentication → Sign In / Providers, turn on Allow anonymous sign-ins. Anyone can make an account this way, but rooms still need their passcode, so strangers see nothing. Supabase limits anonymous sign-ups to 30 per hour per IP address.
   • With an email code. Supabase sends the codes, but its built-in email only reaches your project's own team members (2 an hour), so connect an email service over SMTP. Resend has a free tier, and Postmark, Amazon SES or your mail provider's SMTP work the same way. With Resend:

     1. In Resend, add and verify a domain you own, such as mail.example.com.

     2. Create an API key with Sending access, restricted to that domain.

     3. In Supabase, open Authentication → Emails → SMTP Settings, turn on Enable custom SMTP, and fill in:

        Field	Value
        Sender email	an address on your domain, such as login@mail.example.com
        Sender name	squad-chat
        Host	smtp.resend.com
        Port	465
        Username	resend
        Password	the Resend API key

     4. Under Authentication → Emails → Templates, edit Confirm signup and Magic Link so they show the code. For example, subject Your squad-chat code and body:

        <h2>squad-chat</h2>
        <p>Your sign-in code:</p>
        <p style="font-size:28px;font-weight:bold;letter-spacing:4px">{{ .Token }}</p>
        <p>Type it into Claude Code. It expires in one hour.</p>
        

     5. Try it: sign in with your own email. Each code shows up under Emails in Resend's dashboard, with its delivery status.

5. Share the server with your friends: the project URL and the publishable key, from Project Settings → API Keys. Everyone, you included, connects with them.

(back to top)

Roadmap

• Supabase backend: rooms with passcodes, RLS, rate limits, 30-day retention
• Email-code sign-in and a Node bridge for Realtime presence and messages
• Catch-up after network drops, and a watchdog for stuck reconnects
• Docked pane, compact pane, one-line band and status line
• Chat bubbles, room tabs, unread markers and @mention toasts
• Leave and delete rooms
• Bring your own server, with sign-in by name or by email code
• /chat-name to change your display name
• Typing indicators
• A polling mode for the Claude Code desktop app, which can't start the bridge

See the open issues for proposed features and known issues.

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Acknowledgments

• Supabase, for auth, Postgres and Realtime
• Resend (optional), for delivering sign-in codes on servers that use email sign-in
• glowup, whose classic pack inspired the palette and card layout
• Shields.io and Hits, for the badges
• Best-README-Template, for this README's layout

(back to top)