convez.ai
AgenteAutomaçãoAvançado
josephhaenel

Hivemind

josephhaenel/Hivemind

Pair-programming para agentes de IA com evitação de colisão e sincronização ao vivo

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent de colaboração em tempo real para múltiplos agentes de IA codificando o mesmo repositório. Implementa evitação de colisão ao nível de símbolos, sincronização de arquivos via CRDT e um sistema compartilhado de decisões que injeta regras do time automaticamente nos agentes.

Instalação

$npx convez-ai josephhaenel/Hivemind

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Múltiplos agentes Claude Code editando o mesmo repositório sem sobrescrever trabalho um do outro
  • Mob-programming com agentes de IA mantendo coesão de regras e convenções do time
  • Sincronização live de contexto entre sessões de agentes para colaboração coordenada

Veredito

Solução sofisticada para um problema real: coordenação de múltiplos agentes de IA contra a mesma base de código. A arquitetura com CRDT + claims de símbolo é sólida, mas requer infraestrutura de servidor compartilhado e integração com Claude Code/Codex — uso limitado a teams com esse setup específico.

README

A tradução para o português deste README ainda está na fila.

Hivemind

CI

Multiplayer for AI coding agents. Two or more people coding the same repository — each with their own Claude Code / Codex session — without overwriting each other's work, and seeing each other's changes live.

Pair-programming and mob-programming tools assume humans typing. AI agents don't type — they rewrite whole functions and files in a single shot. That breaks the usual assumptions, and it's the problem this project is built around.


Why this is a hard problem

When two people each drive an AI agent against the same codebase, two things go wrong fast:

  1. Silent clobbering. Agents rewrite entire functions atomically. If two agents touch the same function, a naïve character-level CRDT will happily merge both rewrites into something that compiles-but-is-wrong. Convergence is not correctness.
  2. No shared awareness. Each agent has its own context window. Neither knows what the other is doing, deciding, or about to overwrite.

So the core insight driving the design: the CRDT is only transport + convergence. The actual value is collision avoidance — claiming a region of code before writing to it.


What it does

  • Collision avoidance, down to the symbol. Before an agent edits, it claims the region — at the level of the individual function/symbol, so two agents can safely work in the same file at the same time. If another agent holds it, the edit is refused (agent-vs-agent → hard block; a human involved → soft warn). Enforced at the Claude Code hook and, optionally, at the sync daemon — so even a plain-editor save can't bypass it.
  • Live file sync. Edits propagate between collaborators' working trees in real time over a shared CRDT.
  • A shared brain that learns. Teams record "decisions" — constraints, conventions, interface contracts. The relevant ones are auto-injected into the agent the moment it claims a file to edit (on the human-involved path too), so the team's rules reach the agent exactly when they matter — no prompting, no pull. Agents can also ask it (hive ask "what's our error-handling convention?"), it flags contradictions when a new decision opposes a live one, and it self-populates — hive capture surfaces your recent edits that still need a decision recorded. All keyword/heuristic and dependency-free; an optional LLM layer is a future seam.
  • Live awareness dashboard. The coordination server serves a dark, auto-refreshing web view of who's online, who's editing what, and recent decisions — open https://<server>/ and enter the token.
  • Durable + secure. Persistence (decisions survive restarts) and a shared-secret auth token for remote deployments.

How it works

flowchart LR
  subgraph A["Alice's machine"]
    CCA["Claude Code"] --> HA["pre/post-tool hooks"]
    HA --> DA["sync daemon"]
    DA <--> FSA[("working tree")]
  end
  subgraph B["Bob's machine"]
    CCB["Claude Code"] --> HB["pre/post-tool hooks"]
    HB --> DB["sync daemon"]
    DB <--> FSB[("working tree")]
  end
  subgraph S["Shared server"]
    COORD["coordination server<br/>claims · presence · decisions"]
    RELAY["sync relay<br/>CRDT, one doc per repo"]
  end
  HA -->|"claim before edit"| COORD
  HB -->|"claim before edit"| COORD
  DA <-->|"CRDT sync"| RELAY
  DB <-->|"CRDT sync"| RELAY

Two planes:

  • Control plane (claims + shared brain). A Claude Code PreToolUse hook calls the coordination server to claim the target region before an Edit/Write; PostToolUse releases it. The coordination server is a single, linearizable authority that hands out fence tokens so a stale lease can never overwrite a newer one. A successful claim also returns the decisions relevant to that file/symbol, which the hook surfaces to the agent — so "claim the code" and "learn the local rules" are the same step.
  • Data plane (sync). A per-machine daemon mirrors the gitignore-scoped working tree into a shared Yjs CRDT via a relay: local writes become CRDT edits; remote edits get written back to disk. A "shadow" map breaks the feedback loop in both directions.

The two planes compose: the daemon can check a claim before broadcasting a local edit, so collision avoidance covers edits that bypass the hook entirely.


Repository layout

PathWhat
packages/coordination-mcp-serverClaims / presence / decisions. An MCP server (hive_claim, hive_whos_editing, hive_post_decision, …) plus REST shims for the hooks. Fence tokens, TTL+heartbeat leases, party-dependent policy.
packages/sync-relayMinimal Yjs CRDT websocket relay — one document per repo, fans updates out to peers.
packages/sync-daemonPer-machine disk⇄CRDT mirror; optional daemon-side claim enforcement.
docs/designThe full design specs (see below).
deployOne-command self-host setup for a VPS (Caddy + TLS + systemd + firewall).
examplesRunnable end-to-end demos.

Try it locally (no setup)

npm run install:all
npm run build
npm run demo          # collision avoidance + live sync together
npm run demo:enforce  # a hook-bypassing edit gets blocked & reverted
npm run demo:persist  # state survives a relay restart
npm test              # coordination core (unit tests)

npm run demo spins up the coordination server, the relay, and two daemons on two temp dirs, drives the real Claude Code hooks, and proves the whole loop: same file → blocked, different files → fine, edits sync live, release frees the region.

Use it with real Claude Code, or host it for your team

  • Local / one machine: see QUICKSTART.md.
  • Self-host on a VPS (for you + collaborators): see deploy/README.md — one script sets up TLS (via sslip.io, no domain required), a non-root service user, systemd, a firewall, and an auth token, then prints the exact connection settings your collaborators paste in.

Design docs

This was designed spec-first, and the specs are worth reading on their own:

  • docs/design/sync-loop.md — the git-baseline ↔ CRDT-overlay synchronization model (the production target: epochs, durable landing, offline reconnect, conflict-as-data).
  • docs/design/coordination-mcp.md — the claims/presence/decisions layer (region identity, fencing, the agent-vs-human policy, partition behavior).

Both specs were produced and adversarially hardened with multi-agent workflows — independent agents designed each dimension, then a panel of skeptics attacked the design and the holes were folded back in. Mechanisms in the specs are tagged with the specific failure scenario they defend against.


Status & scope

This is a working MVP, deployed and live: collision avoidance (file and symbol level), live sync, the auto-injected decisions brain, live presence, persistence, and auth all function and are covered by demos/tests. Current simplifications (tracked toward the production design in the specs):

  • the CRDT is the live state (the git-baseline/epoch landing model is specified, not yet built);
  • text files only, under 512 KB; rename = delete+create;
  • shared-token auth (good for a team you invite; multi-user accounts are a later milestone);
  • conflict-as-data (diff3) is deferred — a CRDT lacks the shared ancestor diff3 needs, so concurrent same-region edits are kept safe by block/revert rather than three-way merge.

Contributions and ideas welcome — start with the design docs.

Roadmap

All four planned milestones have shipped and are deployed live (full detail + what's next in docs/ROADMAP.md):

  • ✅ CI & tests — build + test + integration demos on every push.
  • ✅ Frictionless onboarding — hive init wires the hooks, registers the MCP server, and writes a CLAUDE.md in one command; hive up / hive status. (Remaining: publish to npm for clone-free npx @hivemind/cli.)
  • ✅ Agents use the shared brain — relevant decisions are auto-injected at claim time; agents also get hive who / hive decisions / hive decide and the matching MCP tools.
  • ✅ Awareness dashboard — a live web view of who's online, claims, presence, and decisions.
  • ✅ Region-level claims — a dependency-free symbol resolver lets two agents edit different functions in the same file. (diff3 conflict-as-data intentionally deferred — see Status & scope.)

Next: the git-baseline/epoch landing model, live dashboard push (SSE instead of polling), and richer symbol resolution.

License

MIT © Joseph Haenel

Ver o original no GitHub

Bom para

Relacionados