Huddle - Quadro Compartilhado para Agentes Paralelos
bcmyguest/huddle
Memória compartilhada entre agentes paralelos, acionada por hooks do editor
Ver no GitHubAgent que sincroniza planos e estado entre múltiplos agentes de código (Claude Code e opencode) rodando em paralelo no mesmo repositório, sem daemon ou servidor. Usa hooks do editor para garantir que cada agente veja o trabalho do outro em tempo real, evitando conflitos silenciosos em arquivos compartilhados.
Instalação
npx convez-ai bcmyguest/huddle1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Coordenação de agentes desenvolvendo frontend e backend simultaneamente
- Sincronização de mudanças em superfícies compartilhadas (schemas, migrations, tipos)
- Aviso automático de conflitos de edição entre agentes concorrentes
- Rastreamento de planos aprovados entre agentes sem intervalo manual
Veredito

Solução técnica madura para um problema real: agentes paralelos precisam de sincronização de estado low-noise. O design é elegante (hook-driven, sem daemon), a integração com Claude Code e opencode é sólida, e os mecanismos de toque (touch decay) são pragmáticos. Essencial para fluxos multi-agente em repositórios complexos.
README
A tradução para o português deste README ainda está na fila.
huddle
A shared, hook-enforced board so parallel coding agents stay aware of each
other. Run one agent on the frontend and another on the backend, in the same
repo, on separate features. huddle lets each see what the other is about to
build, without a daemon, a server, or the agents having to remember to check in.
Works for Claude Code and opencode, and across them: a Claude Code agent
and an opencode agent whose cwd is in the same repo share one board.
It's a thin memory layer the agents can't forget to use: the reads (and, on Claude Code, the plan-writes) are driven by editor hooks, not by the model choosing to.
Pairs with handoff (capture state) and
pickup (resume state). Where those move
work across time, huddle shares it across concurrent agents.
What it does
One file store. No daemon, no server. The editor's hooks drive it:
| Moment | Effect |
|---|---|
| session begins | injects the room's active board into context |
| every turn | injects only sibling entries new since your last turn |
| a plan is approved | publishes that plan to the room |
| a shared surface is edited | publishes a contract entry naming the file siblings depend on |
| you and a sibling edit the same file | your next prompt warns you (touched-set overlap) |
Reads are guaranteed (injected context, the model can't skip them). Writes are hook-driven. The board gains an entry at milestones — a plan approved, or a shared-surface file edited — not every turn, so it stays low-noise.
A contract entry catches the cross-agent breaker that worktree isolation
can't: two agents in different files, where one changes a shared surface
(an API schema, a DB migration, a shared type, .env.example, a dependency
manifest) that the other silently depends on. Surface edits auto-publish; one
current entry per file (re-editing supersedes), so it stays low-noise.
Every edit (not just surfaces) also records a lightweight touch. Reads are
filtered through it: a sibling's contract on a file you're currently editing is
flagged ⚠, and if you and a sibling are editing the same file your next prompt
warns you once. Touches decay after 15 min (HUDDLE_TOUCH_TTL), so the warnings
follow what's actually in flight rather than lingering.
Claude Code
Three hooks, each enforced so the model can't skip a read or forget to post:
| Hook | Fires | Effect |
|---|---|---|
SessionStart | session begins | injects the room's active board into context |
UserPromptSubmit | every turn | injects only sibling entries new since your last turn |
PostToolUse (ExitPlanMode) | you approve a plan | publishes that plan to the room |
PostToolUse (Edit|Write|MultiEdit) | you edit a shared-surface file | publishes a contract entry for that file |
SessionEnd | session ends | removes this session's transient markers (board entries are kept) |
opencode
The same store, reached through opencode's plugin API. opencode/huddle.ts is a
thin bridge that shells out to the same hook scripts, so the on-disk format and
rooms are identical and the two editors interoperate.
- Reads map to
chat.message+experimental.chat.system.transform: the full board is injected on your first prompt, then only new sibling entries on every prompt after. Same guarantee as Claude Code. - Plans map to
session.idlefor opencode's plan agent, the structural twin of Claude's plan mode: when a plan-mode turn finishes, its plan is posted to the room. opencode has noExitPlanModeevent, so this is the closest faithful trigger. Build-mode-only sessions still read the board but do not post, so run the planning turn in plan mode to publish. contractentries publish from opencode edits too:tool.execute.afteron theedit/writetools is the twin of Claude'sPostToolUse(Edit|Write), so an opencode edit to a shared surface posts (and supersedes) a contract the same way. The multi-filepatchtool is covered as well — one contract per file it touches, read from the paths opencode reports in the tool result.- Marker cleanup maps to
session.deleted— opencode's nearest thing to a session end — which clears that session'sseenmarkers and sweeps orphans, the way Claude'sSessionEndhook does.
Rooms
A room = the git repo basename of your working directory. Two agents whose
cwd is in the same repo automatically share a room, regardless of which editor
each runs. (Monorepo split by sub-package is a later addition.)
Agent identity
Each entry is tagged with who wrote it. Identity resolves as:
HUDDLE_AGENTenv var (export it per terminal:export HUDDLE_AGENT=frontend)- else the current git branch
- else
unknown
Set HUDDLE_AGENT in each terminal so the board reads frontend/plan,
backend/plan, etc.
Store
~/.claude/huddle/<repo>/
<epoch>-<agent>-plan.md # plan entry (one per approval), append-only
<stamp>-<agent>-contract.md # shared-surface change; one current per (agent, path)
.touched-<agent> # rolling set of files this agent edited (TTL-pruned)
.seen-<session_id> # per-session marker for incremental reads
.seen-overlap-<session_id> # overlaps already warned this session
Override the root with HUDDLE_HOME. Entries are plain markdown with frontmatter.
A plan (what an agent intends):
---
agent: backend
room: acme
kind: plan
status: active
ts: 2026-06-15T14:03:00Z
---
Adding `role` field to /users response. Frontend: expect it nullable until migration N.
A contract (a shared surface that moved — surface is one of
api/schema/types/config/deps, path is repo-relative). Re-editing the
same path supersedes the prior entry, so the board holds one current line per file:
---
agent: backend
room: acme
kind: contract
surface: api
path: openapi.yaml
status: active
ts: 2026-06-15T14:03:00Z
---
changed openapi.yaml (api surface) — re-check your assumptions about it.
Install
Claude Code
No clone needed — add the repo as a plugin marketplace:
claude plugin marketplace add bcmyguest/huddle
claude plugin install huddle@huddle
# restart Claude Code so hooks load
(Cloned it already? /plugin from a session adds the local directory instead.)
opencode
# 1. point huddle at this repo so the plugin can find the hook scripts
export HUDDLE_ROOT=/path/to/huddle
# 2. load the plugin (globally here; or drop it in a project's .opencode/plugin/)
ln -s "$HUDDLE_ROOT/opencode/huddle.ts" ~/.config/opencode/plugin/huddle.ts
Put export HUDDLE_ROOT=... (and HUDDLE_AGENT) in each terminal's shell rc so
opencode inherits them, then restart opencode. The plugin fails open: if it
can't find the scripts it disables itself and never blocks a prompt.
Then in each terminal you spawn an agent in (either editor):
export HUDDLE_AGENT=frontend # or backend, infra, ...
Limits (by design)
- Not real-time. A sibling's plan reaches you at your next prompt, not mid-turn.
- Sync points are plan-approve and shared-surface edits. A long-running agent that
never re-plans and never touches a contract surface goes quiet until it does.
(Hooking into
handoffis a planned further sync point.) - On opencode, only plan-agent turns post plans (no plan-approval hook exists), but contracts publish from any edit, so build-mode sessions still post those.
- No locking. Entries are append-only files; concurrent writes don't collide because each is a uniquely named file.
jqand GNUfind/daterequired (Linux/standard dev box). The opencode plugin additionally needs opencode's Bun runtime (it ships with one).