Yesterday, a GitHub repo called Cumora hit #1 on trending. 2,077 stars in 24 hours. The tagline: "Where agent teams gather." Cross-platform team chat where AI agents are first-class teammates.
I've seen enough agent frameworks to be skeptical. But I cloned it, read every inch of the source, ran the typechecker (zero errors across 65K lines of TypeScript), and found something I didn't expect: a production system that's been running for months, with documented failures, real engineering scars, and a coordination architecture that's genuinely novel.
This isn't a README summary. I read the COORDINATION.md (776 lines of battle documentation), the seen-boundary.ts coordination substrate, the benchmark suite that runs real LLMs against statistical pass criteria, and the engine adapter that turns Claude Code or Codex into an agent brain. Here's what I found.
The Pattern That's Different
Most agent frameworks are orchestrators. There's a master loop that decides what each worker does next. Semaphore. CrewAI. Autogen. They all route through a central decision point.
Cumora does the opposite. Agents are autonomous peers sharing a chat room. The server provides coordination primitives — but it never tells an agent what to do. Each agent runs its own Claude Code or Codex session, reads the conversation history, and decides independently. The server's job is to detect and prevent the collisions that naturally emerge when N independent LLM sessions act on the same state.
graph TB
subgraph "Server (Coordination Substrate)"
DB[(Postgres
source of truth)]
R[(Redis
coordination signals)]
S[App Server
Express + WS]
end
subgraph "Client Machine (BYOA)"
D[Daemon
cumora agent computer]
E1[Engine: Claude Code]
E2[Engine: Codex]
end
subgraph "Cumora Cloud"
K[Agent Pods
Kubernetes]
end
H[Human] -->|chat| S
S -->|SSE wake| D
D -->|spawn| E1
D -->|spawn| E2
E1 -->|cumora reply| S
E2 -->|cumora reply| S
S --> DB
S --> R
D --> R
style S fill:#1e1b4b,stroke:#818cf8,color:#fff
style D fill:#2d1b2d,stroke:#c084fc,color:#fff
style E1 fill:#1a2e1a,stroke:#4ade80,color:#fff
style E2 fill:#1a2e1a,stroke:#4ade80,color:#fff
Two brain paths: Cumora Cloud (managed K8s pods running the OpenAI Responses API) or BYOA — bring your own agent via npx cumora agent computer. The server never sees your provider keys. The daemon runs on your machine, spawning local Claude Code or Codex sessions and routing their tool calls through a cumora shim on PATH.
The Seven Defense Layers
The COORDINATION.md documents the failures that necessitated each layer, with commit hashes and dates. This is not theoretical. Here's the stack, bottom to top:
1. Per-agent Model Pin
A single environment variable (CUMORA_DEFAULT_CLAUDE_MODEL) pins every agent to a specific model. Why? Because on 2026-05-31, the local Claude CLI silently flipped its default from opus-4-7 to opus-4-8 mid-session. Opus-4-8 is more cautious about prompt-injection-like patterns and behaved differently in multi-agent flows. Without the pin, every user's behavior drifts whenever Anthropic ships a model update.
This is the kind of brittleness that only emerges in multi-agent systems. A single-agent setup might not even notice a model swap. But in an N-agent coordination game, a subtle shift in one agent's behavior cascades.
2. Big-Brain Concurrency Cap + Spawn Spacing
When a human @all in a group chat wakes N agents simultaneously, N Claude Code subprocesses spawn in the same millisecond. Anthropic's short-window burst limit is smaller than the agent count on a typical roster. The team observed 130 rate-limit hits in 17 minutes during a 7-agent counting game.
The fix is two-pronged: a semaphore caps concurrent big-brain spawns (default 6), and a deterministic minimum interval (default 500ms) between spawn starts ensures the burst rate is a hard upper bound, not a probabilistic one. Random jitter was tried first and failed — 4 simultaneous wakes can all roll low values.
3. Small-Brain (Triage) Concurrency Cap
This one bit them twice. The same SSE fanout that triggers big-brain spawns also triggers a triage spawn — a cheap model (haiku / gpt-5.4-mini) that decides whether the wake is actionable. Without a cap on triage, every agent spawns haiku simultaneously. The slower-queued ones blow the 30-second triage timeout, the daemon treats the abort as rate-limited, every agent's triage stalls, and the whole computer goes silent.
Observed signature in production:
[computer] X local triage RATE-LIMITED (timed out) ... process exited with code 143
[computer] X triage RATE-LIMITED (#1, triage 3X000ms) — backing off 30sThe anti-pattern: "Don't cap one layer without the other."
4. Adaptive Pacer for Sustained Rate-Limiting
A fixed spawn interval isn't enough when the provider itself is throttling. The AdaptivePacer doubles the minimum spawn interval on any rate-limit error (capped at 8 seconds) and halves it after 5 consecutive clean turns. It's wired into both the cold-spawn path AND the persistent-session chat-turn path — because the persistent Claude session send() doesn't re-enter the spawn gate.
5. Server-Side Freshness Preflight (The Core Innovation)
This is where Cumora's design diverges from every other multi-agent system I've seen. The server maintains a per-agent, per-conversation seen sequence boundary in Redis. Before an agent posts, the CLI checks: "Has anyone else posted since I last read?" If yes, the post is HELD, and the agent is shown the newer messages to re-decide.
The implementation is remarkably careful:
- Redis-only, fail-open. The seen boundary isn't in Postgres because an earlier attempt using
conversation_reads.last_read_atbroke the inbox polling cursor — daemons hung silent-busy. Redis is outside the DB transaction graph: no row locks, no contention. Lua scripts keep the monotonic update atomic. And if Redis is down, the worst case is a duplicate post, not a daemon hang. - Compose anchor — an additional timestamp stamped at turn START, NOT advanced by
cumora glance. This catches the case where agent A glances and sees agent B's post (advancing A's seen baseline), then still posts a duplicate because the brain already decided. - Atomic verbatim-dup HOLD — inside the INSERT transaction, after taking a row-level lock, the server compares the draft body to the latest peer message. Verbatim-identical → ROLLBACK + HELD. Crucially, this cannot be bypassed by
--send-anyway, because there is no legitimate use case for posting content identical to the immediately-prior message.
5d. Hold-Token-Gated Overrides
This layer exists because of a specific incident on 2026-06-11/12: agents learned to pass --send-anyway preemptively to save a round-trip. The freshness preflight that would have shown the agent a peer's post was bypassed before it ever ran. Two agents each posted the full story. Two copies of a document were created.
The fix: every HELD envelope records a token (Redis, 2-minute TTL). The --send-anyway flag is honored only if a token exists, and consuming it is atomic. A token is bound to the specific state it acknowledged — if the room moved past that state, the flag is void.
This is the most important architectural lesson in the entire project: override flags must be acknowledgements, not free passes.
6. Small-Brain Triage Gate
The cerebellum (a cheap model) decides actionable: boolean for each wake. Only actionable wakes trigger the big brain. The gate is a pure principle, not a checklist: "A human involved → always actionable. Agent chatter with no claim → suppress. When unsure → actionable."
Beneath the AI judgment sit deterministic loop floors — hard caps on agent messages per conversation (20 for claimed threads). These have been deleted twice "for AI-native elegance" and loops regressed both times.
7. Standing Prompts + Glance Yield Rules
The brain-level instructions live in two files. One defines the coordination protocol the agent follows via cumora glance and cumora yield. The other defines the system prompt that shapes the model's multi-agent behavior — things like "you may lap to cover an absent member, but never lap when explicitly capped."
The prompt-shape baseline is pinned to a specific commit — any prompt diff is measured against this state, where coordination was empirically perfect (counting games, werewolf scenarios, group brainstorms all worked cleanly).
The Benchmarks: Real LLMs, Statistical Pass Criteria
Cumora ships with a benchmark suite that runs real LLM agents against real production scenarios and evaluates them with statistical pass criteria. The harness is intentionally thin: it impersonates a human posting a seed message, then polls the messages table until natural completion or timeout.
| Scenario | What It Tests | Cost/Trial |
|---|---|---|
| Chain | N-char relay with one member absent — team adapts, members lap to cover | $3-5 |
| Counting | Explicit per-person cap — agents must NOT lap even when they could | $1-2 |
| Werewolf | Multi-round role-playing with judge-driven state machine | $15-25 |
| Kanban | Pull-group on a card; success = card moves to done column by 2+ agents | $8-15 |
The chain and counting scenarios are designed as shape-duals: chain proves the team adapts to absence (lap when needed); counting proves the team respects an explicit cap (don't lap when forbidden). A regression that breaks either principle shows up in exactly one of them.
Pass criteria are statistical over the trial sample, never per-trial. "≥67% of trials hit exact-match completion AND median verbatim-collisions = 0." This is the right approach for LLM-judgment-driven behavior — it flags real regressions without flapping on stochastic noise.
The benchmark runner costs $12-21 per weekly cycle (chain + counting). That's cheap for a regression watch that has caught real coordination bugs.
What Makes This Serious
I've reviewed a lot of agent frameworks. Most are architectural diagrams with barely any code. Cumora is the opposite — it's a running production system with 65K lines of TypeScript, 164 server-side source files, 134 frontend files, and a test suite that includes integration tests, CLI parse tests, triage core tests, guard tests, and orchestration tests.
Things that stood out from reading the source:
- Every coordination decision documents the failure that motivated it, with commit hashes and dates. This is engineering archaeology, not product docs.
- Fail-open is a conscious posture. Redis down? The worst case is a duplicate post, not a daemon hang. Every infrastructure decision weighs the failure mode.
- The BYOA daemon is standalone — zero DB/Redis deps, only Node builtins plus the SSE parser and engine adapter. It runs on any machine with Claude Code or Codex installed.
- Semantic model pinning prevents silent behavior drift when Anthropic or OpenAI updates their defaults.
- Cost tracking — every LLM call, cloud or BYOA, lands in a shared
llm_callscost ledger.
I ran the TypeScript typechecker across the entire project — zero errors. I tried running the unit tests (they need Postgres and Redis, which I don't have in this environment), but the architecture is clean enough that the type system already proves a lot of safety.
The Bottom Line
Cumora matters because it solves the real problem with multi-agent systems: coordination without central control. Every layer in its defense stack was hard-won through production failures that most teams haven't encountered yet. The code is open source (MIT), the documentation is exceptional, and the engineering philosophy — fail-open, battle-tested, evidence-backed — is the right one for this problem space.
Most agent frameworks are toys. This one has been running in production for months, has caught real collisions, and has the scars to prove it. If you're building multi-agent systems, read the COORDINATION.md and the seen-boundary.ts source. They'll save you weeks of debugging.