openhuddle

Multi-human collaboration mode for Claude — share a single Claude session with your team.

Status: alpha · MVP under construction · MIT license

openhuddle lets multiple humans share a single Claude session with the same context window and the same transcript. Product can drive the PRD draft, engineering can drop in technical context, and Claude listens to everyone — responding only when invoked. The output is a single markdown artifact that the team co-authors live.

Install (target — not yet published)

Runtime: Node 22+ (uses fs.glob).

npx openhuddle@latest start --workspace ./my-feature --artifact ./prd.md

The host runs the command, gets a shareable URL. Joiners open the URL in any browser — no install required.

Configuration

@claude responses require an Anthropic API key. Two ways to provide it:

1. .env file in the project root (recommended for dev):

   cp .env.example .env
   # edit .env, paste your key (keys at console.anthropic.com/settings/keys)

   .env is gitignored. The file is loaded automatically on openhuddle start.

2. Shell export — export ANTHROPIC_API_KEY=sk-ant-…. Real env vars take precedence over .env.

Without a key, the host still runs in chat-only mode — humans can talk to each other, but @claude is disabled and openhuddle doctor will warn.

Quick start (current dev workflow)

git clone <this-repo>
cd openhuddle
npm install
cd web && npm install && cd ..
npm run build:web         # build the React client into web/dist/
npm run dev -- start      # boots the host

Then open the local URL printed by start (it includes the session token) in a browser.

For HMR-enabled client dev, run two terminals:

# Terminal A — Node host
npm run dev -- start

# Terminal B — Vite dev server with /ws + /health proxied
npm run dev:web

# then open http://localhost:5173/?token=… (token from Terminal A's banner)

How it works

• Host runs the daemon. Joiners connect via browser (WebSocket, M1+).
• Humans chat freely; Claude only answers when @claude-mentioned.
• Claude reads anywhere in the workspace and writes only the artifact.
• All actions stream live: typing indicators, "Claude is reading X", artifact panel updates.
• Sessions persist on disk and resume after host restarts.

Status

Active development. Milestone progress:

• M0 — Project skeleton, hello server
• M1a — Server-side WebSocket gateway, event log, session state
• M1b — React + Vite web client (chat + join + connection status)
• M1c — Typing indicators + presence sidebar
• M2 — @claude integration via the Claude Agent SDK
• M3 — Tools (Read/Glob/Grep + artifact Edit/Write) gated by PreToolUse hooks (server-side)
• M3.5 — Web UI for tool calls + artifact panel
• M4 — Auto-tunnel via cloudflared
• M5 — Compaction (auto + manual)
• M6 — Resume from event log
• M7 — Doctor + npm publish

Architecture

See src/ for the layout:

• src/cli/ — entry point and subcommands (start, resume, doctor)
• src/server/ — HTTP, WebSocket, session state, event log, tunnel manager
• src/agent/ — Claude Agent SDK runtime, task queue, PreToolUse/PostToolUse hooks, compaction
• src/protocol/ — wire protocol (events + commands)
• src/shared/ — id generation and other utilities

Security notes

• Session token in the URL. The local URL printed by openhuddle start includes the session token as a query parameter. That's convenient for sharing but means the token can land in browser history, server access logs, and HTTP Referer headers from any external link the page later loads. Acceptable for the MVP (single host, trusted network), but the share URL pattern (M4 + cloudflared) needs hardening — likely a one-time-use redirect that exchanges the URL token for a session cookie.
• Read-only filesystem access for joiners. Once tools land (M3), the host's workspace is readable by anyone with the share link via Claude. The host consents by running start with that workspace; treat the workspace as "what you'd be willing to put on a screen-share."

License

MIT.