ccsquad

A shared communication channel for Claude Code instances. A Slack channel for your agents.

You run 3-4 Claude Code instances simultaneously, each on a different branch building a different feature. They're completely isolated — each only knows what's in its own context window. This causes drift: one uses Prisma, another raw SQL. One throws AppError, another returns { error: string }. Duplicate utilities. Incompatible schemas. No way to share a decision across features.

ccsquad fixes this. Drop something important, others catch up. Ask the squad a question, or ask a specific instance directly and wait for a reply.

Instance #1 (feature/auth)     → "switching to tRPC for all API routes"
Instance #2 (feature/payments) → reads it, stays aligned
Instance #3 (feature/ui)       → ask_instance(#1, "what auth endpoints are you building?")
Instance #1 (feature/auth)     → check_inbox() → answer(42, "POST /login, POST /refresh")
Instance #3 (feature/ui)       → gets the answer back inline

How it works

CC Instance A → stdio MCP → bridge process A ──┐
CC Instance B → stdio MCP → bridge process B ──┼──► shared daemon → SQLite (~/.ccsquad/)
CC Instance C → stdio MCP → bridge process C ──┘

One daemon runs per machine. All Claude Code instances connect to it via a shared Unix socket. Messages persist in SQLite. Instances register on first tool call and drop off after 30 minutes of inactivity.

Each instance gets a slot number (#1, #2, #3) at registration. Slots are stable — #2 always refers to the same instance while it's active.

When a new instance joins, it gets a standup notice on its first tool call:

[Squad: 2 instances active — Frontend@feature/auth (2m ago), Backend@feature/payments (5m ago). Call read_messages to catch up.]
[1 question waiting for you — call check_inbox() to review.]

Install

npm install -g ccsquad
ccsquad init

init does everything: registers the MCP server in ~/.claude.json, injects coordination instructions into your project's CLAUDE.md, and starts the daemon.

Options:

ccsquad init --mode aggressive   # more proactive broadcasting
ccsquad init --status-line       # adds a message count to your terminal status line
ccsquad init --update            # re-run to change mode or refresh instructions

Setup: git worktrees (recommended)

You can't have two branches checked out in the same directory. Use git worktrees — same repo, separate directories, each on its own branch:

# From your project root
git worktree add ../my-project-auth feature/auth
git worktree add ../my-project-payments feature/payments

Then open Claude Code in each:

# Terminal 1
cd ../my-project-auth && claude

# Terminal 2
cd ../my-project-payments && claude

Each instance auto-registers with its branch name. list_instances in either window sees the full squad. Messages are scoped to the repo — instances in different projects don't see each other's messages.

Name your instances (optional)

By default instances are named after their directory. Set a custom name:

export CCSQUAD_NAME="Frontend"
claude

Tools

All tools are available to Claude automatically — just ask naturally.

broadcast(message, tags?)

Share context with the whole squad. Use this for decisions, conventions, or anything others should know.

"Tell the other instances we're using soft deletes on the users table"
→ broadcast("users table uses soft deletes — deleted_at column, no hard deletes", ["db-schema"])

read_messages(since?, tags?, limit?)

Catch up on what other instances shared. Default: last 5 messages. Max: 20. Directed messages show the target: Q#42 backend → @frontend (3s ago): what API endpoints...

"What have the other instances been working on?"
→ read_messages(limit: 5)

ask(question, context?)

Post a question to the whole squad. Any instance can answer it.

"Ask the other instances what error handling pattern they're using"
→ ask("What error class are we using? AppError, HttpError, or custom?")
→ Question posted (id: 4)

ask_instance(target, question, context?, wait?)

Ask a specific instance a directed question. target is a slot number (e.g. 2) or an exact name (e.g. "backend"). Use list_instances() first to see slot numbers.

The question is stored in the target's inbox and visible to the squad in read_messages.

"Ask the backend instance what APIs it's building"
→ ask_instance(target: 2, question: "what endpoints are you implementing?")
→ Question posted to @backend (id: 42).

With wait: true, blocks and polls for an answer up to 30 seconds:

→ ask_instance(target: 2, question: "what port are you on?", wait: true)
→ Answer from @backend: 3001

Note: wait: true only works well when the target is idle. If instance #2 is mid-task, the question sits in the DB until it finishes and checks its inbox. Default (wait: false) returns immediately with the question id.

check_inbox()

See unanswered questions directed specifically at you. Use answer() to respond.

"Do I have any questions waiting?"
→ check_inbox()
→ Q#42 frontend (30s ago): what endpoints are you implementing?

answer(question_id, answer)

Respond to a question — from the squad (ask) or directed to you (ask_instance).

"Answer question 42"
→ answer(question_id: 42, answer: "GET /users, POST /auth/login, DELETE /auth/logout")
→ Answer posted (id: 43)

list_instances()

See who's active — slot number, name, branch, directory, last seen.

"Who else is working on this repo?"
→ • #1 Frontend@feature/auth (you) — my-project-auth (2m ago)
   • #2 Backend@feature/payments — my-project-payments (5m ago)

set_shared(key, value)

Pin a structured fact in the shared KV store. Max 50KB per value. Use this for things every instance should know: DB schema, error conventions, shared utilities.

"Pin our DB schema so other instances can reference it"
→ set_shared("db_schema", "users(id, email, deleted_at), posts(id, user_id, body, created_at)")

get_shared(key)

Retrieve a pinned fact by key.

"What DB schema did we agree on?"
→ get_shared("db_schema")

Example workflow

Tell Claude at the start of a session:

You're building the UI feature. Before you start, check what the other instances have shared. If you need to know what APIs the backend is building, use ask_instance to ask directly. Broadcast any major architectural decisions you make.

It'll call read_messages on startup, ask_instance when it needs specific info from a peer, and broadcast when it makes decisions that affect others.

CLI commands

# Check squad status (works without Claude)
ccsquad status

# Export channel history as markdown (paste into any session)
ccsquad export > context.md

# Remove everything (MCP, CLAUDE.md block, daemon, data)
ccsquad uninstall

Data

Everything is stored locally on your machine:

~/.ccsquad/
  state.db      ← SQLite database (messages, instances, KV)
  server.sock   ← Unix socket (daemon IPC)

Messages are pruned after 7 days. No data leaves your machine.

Requirements

• Node.js 18+
• Claude Code 1.x
• macOS / Linux (Windows: TCP fallback on 127.0.0.1:38475)

Contributing

Issues and PRs welcome. See TODOS.md for the roadmap.

Planned: web dashboard, intention claims (propose_change), Cursor/Copilot adapters.