Cumora Deep Dive: Treating AI Agents as "Coworkers" in Group Chat
> Research date: 2026-08-21 | Source: github.com/yetone/cumora | Author: yetone (author of avante.nvim)
One-Sentence Take
Cumora's goal is straightforward: make AI agents stop being tools you have to @-mention, and turn them into colleagues sitting in the same office — same roster, same group chat, same DMs, same kanban board, same calendar. Agents have personas, memory, claim work themselves, coordinate without colliding, and can even send and receive real email.
Provenance: Don't Be Fooled by "Four Days"
The repo went public on 2026-08-17 and amassed 2,817 stars and 336 forks in four days. But the roots go deeper: releases trace back to 2026-05-29 (v0.1.60), with a prompt baseline dated 2026-05-28 in the COORDINATION doc. The agent-cli has iterated to v0.1.127. In other words, it was privately polished for nearly three months before being open-sourced — not a weekend project, but a first unveiling of a mature product.
What Problem It Solves
The docs classify multi-agent coordination failures into two types:
- Race collisions: two agents wake at the same moment and both decide to send "3", both INSERT. Classic case: Iris and Marcus both sending "3" in a counting game.
- Reasoning misjudgment: the agent sees the latest state but picks the wrong action (duplicate sends, rollbacks, skipped steps).
chain: N words passed in sequence with one agent deliberately absent — tests whether the team backfills a missing teammate.counting: each agent says one number up to K — tests whether limits are respected.README.md— overview and local setupdocs/BYOA.md— bring your own agent: local Claude Code / Codex / Grok as the braindocs/COORDINATION.md— how agents collaborate without collisions (defense layers + anti-patterns; the best read)docs/email.md— per-agent real email mechanismdocs/SHIPPING.md— evidence-driven feature lifecycle shared by humans and agentsbenchmarks/— real-LLM multi-agent coordination benchmarks (chain / counting / werewolf / kanban)agent-cli/— the published npm packagecumora(BYOA daemon, now v0.1.127)agent-fuse/— Go FUSE driver mounting agent workspaces into cloud pods
The first is handled by code mechanisms; the second only by prompt shaping. A key doc principle: "When the brain makes a clear decision in the correct state, never add code mechanisms to manage it; conversely, don't use prompts to patch holes that should be handled by code."
Two "Brain Paths" — The Cleverest Design
Path one: Cumora Cloud. Each agent lives in a managed pod, with the brain running OpenAI Responses API multi-hop tool loops (bash, files, browser, email, memory, skills...). Platform-managed, always online.
Path two: BYOA (Bring Your Own Agent). Run a npx cumora agent computer daemon on your Mac or VPS, and the agent's brain becomes your local Claude Code / Codex / newly added Grok Build, using your own subscription — the server never touches your keys.
This works because cumora fully decouples "input/output" from the "brain": everything an agent does goes through the same cumora CLI shell, which POSTs to /runtime/cli, with wakeups over SSE. Swap the brain or host; everything else is reused.
The abstraction is Computer as a first-class concept: one managed Computer in the cloud, your Mac and VPS as others. Creating an agent means choosing which machine it lives on. If a machine goes down, the agent shows "asleep", not "broken". There are no special BYOA agents — only agents living on different machines.
Architecture Overview
| Layer | Tech | Notes |
|---|---|---|
| Frontend | React 18 + Vite + TS + Tailwind | desktop / web / mobile / admin share one component set |
| Backend | Stateless Node: Express + ws | Postgres as single source of truth (pg pool + Drizzle), Redis for pub/sub and presence |
| Scaling | Multiple instances behind LB | Synced via Redis bus |
| Cloud agents | k8s pods | Server orchestrates via kubectl; Go FUSE driver mounts workspaces into pods |
| BYOA agents | Daemon on user machines | Local engines, same cumora CLI protocol |
| Edge | Cloudflare Workers | email-gate (inbound email), r2-gate (signed CDN) |
| Costing | Unified ledger | Every LLM call — cloud or BYOA — lands in the same llm_calls table |
Coordination Defense Layers: Where the Real Work Is
Multiple layers, from "always-on, brain-free" to "soft, brain-based":
1. Per-agent pinned model (prod: claude-opus-4-7). The local claude CLI once silently flipped defaults from opus-4-7 to opus-4-8 mid-session, changing multi-agent behavior. Pin, or everyone drifts when Anthropic ships a new model.
2. Big-brain concurrency cap (default 6). Set to 2 earlier, a 7-agent broadcast room queued six deep; tail agents waited 215–359 seconds before speaking. At 6, the whole team thinks in parallel.
3. Hard 500ms spawn interval (MIN_SPAWN_INTERVAL_MS). Random 0–1500ms jitter let four simultaneous wakeups all roll low values and still hammer the API. Fixed intervals make burst rate mathematically 1/interval — no luck involved.
4. Triage (small-brain) concurrency cap of 8. Lesson from 2026-06-02: capping big brains but not triage caused all triage calls to time out → SIGTERM → daemon treated it as rate limiting → entire machine went silent.
5. Freshness gate (seen-cursor): a stale reply is HELD, fed newer messages, and re-decided. Atomic claim of real work units. The triage gate shields the big model up front.
The recurring philosophy: whatever code can handle, don't do with prompts; whatever prompts can shape, don't build in code. This is scar-tissue engineering, not slideware.
Benchmarks: Dares to Validate with Real LLMs
A weekly-run real-LLM multi-agent benchmark suite (chain / counting / werewolf / kanban) catches regressions invisible to unit tests: races, social-inference traps, classifier-outage fallbacks.
A subtle design: chain and counting are "shape duals":
One tests stopping vs. going; regressions in either direction surface in exactly one. Scoring is statistical, not per-run: require "exact completion in ≥67% of trials AND median verbatim collisions = 0" — catching real regressions without noise-induced false positives.
Email Is Real, Not Decorative
Each agent gets a real address (<participantId>.<companySlug>@<EMAIL_DOMAIN>) and can send and receive mail. Inbound flows through Cloudflare Email Routing into the email-gate worker, waking the corresponding agent like any other message. This connects agents to the outside world, not just group-chat self-talk.
Community Signals
| Signal | Value | Read | |---|---|---| | Stars | 2,817 | Four days, steep climb | | Forks | 336 | Abnormally high (usually ~1/20 of stars; here ~1/8) | | Open issues | 9 | Very few; community still observing | | Commit cadence | PRs merged hours ago | Extremely active | | Engines | Cloud + Claude Code + Codex + Grok Build (#23 just merged) | Multi-engine roadmap expanding fast |
The fork ratio, combined with BYOA self-hosting, strongly suggests many forks are people running their own instance — exactly the audience BYOA architecture ignites.
My Verdict, Bluntly
What's fresh. The "agent as coworker" product thesis holds up, especially BYOA shifting cost and key risk to users while decoupling I/O from the brain — a structure that can light up the self-hosting crowd. The coordination defense layers are hard-won lessons.
Three buckets of cold water.
First, cloud brains are locked to OpenAI Responses API while BYOA gets Claude/Codex/Grok — divergent paths that are long-term maintenance debt.
Second, coordination still relies on "prompt shaping + heuristic gates", and the docs admit prompts are a soft mechanism with a ceiling. Benchmarks only cover small teams (6–7 agents); collision rates in large rooms may grow non-linearly — no data yet.
Third, keys never touching the server is a real plus, but the local daemon's security surface (anyone can run npx cumora agent computer) is your responsibility, and the docs' security boundary section is thin.
Who's it for? Teams wanting a few 24/7 "digital coworkers" without handing over data keys — the BYOA route is attractive. If you just want turnkey, wait for the cloud path to prove its stability a bit longer.