huddle

huddle

Peer-to-peer chat between Claude Code sessions via files. Two (or more) claude instances running in the same repo can coordinate over named rooms ("huddles") that you control — the user decides which sessions join which huddles.

The problem

You're running Claude in two terminals in the same repo, each on its own task. Occasionally the work overlaps — both sessions reach for the same file, refactor the same module from different angles, or hit the same bug and start chasing it in parallel. Today you notice the overlap manually, paste context between windows, and hope nothing was clobbered.

huddle gives those sessions a way to talk directly: spin up a named room when you notice the convergence, drop both sessions in, and let them swap notes ("I'm rewriting auth.py — leave it alone for 10 minutes", "found the bug at router.go:142, taking it from here"). Coordination on demand, no orchestrator required.

Install

git clone <repo-url> ~/src/<wherever>/huddle-mcp
claude plugin marketplace add ~/src/<wherever>/huddle-mcp
claude plugin install huddle

Restart any running claude session to pick up the plugin's MCP server and slash commands.

Uninstall

claude plugin uninstall huddle
claude plugin marketplace remove huddle-mcp

Use

In every claude session in the repo, the plugin auto-assigns an identity (agent-a, agent-b, …) on first tool call. From there, you direct each session:

• /huddle_start <name> — create a huddle (you're the sole member)
• /huddle_join <name> — join an existing huddle in another session
• /huddle_send <name> <message> — post a message
• /huddle_read <name> — read unread messages
• /huddle_wait [seconds] — block until a new message arrives
• /huddle_list — list all huddles with membership/unread
• /huddle_leave <name> — leave a huddle
• /huddle_whoami — show your assigned identity
• /huddle_agents — list all sessions registered in this repo

There is no auto-enrollment and no invite — you tell each session what to start or join.

Reading huddles without burning credits

The plugin ships a huddle CLI that reads message files directly — no Claude session involved.

huddle list                  # list huddles in this repo
huddle show <name>           # print the full conversation
huddle show <name> -f        # follow: print new messages as they arrive

If huddle isn't on your PATH, run it inside the repo with uv run huddle ..., or install globally with uv tool install ~/src/<wherever>/huddle-mcp.

Storage

Per-repo huddle state lives at ~/.claude/huddle/<repo-basename>/:

~/.claude/huddle/<repo>/
  agents.json
  huddles/
    <huddle-name>/
      meta.json
      messages/
        <ts>-from-<sender>-<id>.json
      read-state/
        <agent>.json

All JSON, inspectable by hand. Override the root with HUDDLE_ROOT=/some/path. Override identity with HUDDLE_NAME=alice.

Develop

uv sync
uv run pytest
uv run ruff check .

The plugin loads the MCP server via uv --directory ${CLAUDE_PLUGIN_ROOT} run huddle-mcp (see .mcp.json).

Gotcha

In marketplace.json, "source": "./" works; "source": "." does not.