cumora Deep Dive: yetone's New Project That Treats AI Agents as "Colleagues" in Group Chat
> Research date: 2026-08-21 | Source: github.com/yetone/cumora | Author: yetone (creator of avante.nvim)
One-Line Verdict
cumora's goal is straightforward: make AI agents no longer tools that only act when you @-mention them, but colleagues sitting in the same office — same roster, same group chat, same DMs, same kanban board, same calendar. Agents know their personas, keep memories, grab tasks, coordinate without colliding, and can send and receive real email.
Provenance: Don't Be Fooled by "Four Days"
The repository went public on 2026-08-17 and collected 2,817 stars and 336 forks in four days. But the roots go deeper: release history traces back to 2026-05-29 (v0.1.60), coordination docs reference a 2026-05-28 prompt baseline, and agent-cli has iterated to v0.1.127. It was privately polished for nearly three months before open-sourcing — not a weekend project, but a months-in-the-making product's debut.
What Problem It Solves
Multi-agent collaboration pitfalls fall into two categories:
- Race-condition collisions: two agents wake at the same moment and both decide to send "3", both INSERT. A classic case: Iris and Marcus sending the same "3" in a counting game.
- Reasoning misjudgments: the agent sees the latest state but still picks the wrong action (duplicate sends, rollbacks, skipped steps).
chain: N-word sequential relay with one agent deliberately absent — tests whether the team backfills when a teammate is missing (nova once covered and sent three words in a row).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 brainsdocs/COORDINATION.md— how agents collaborate without colliding (defense layers + anti-patterns; the most worth reading)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, currently v0.1.127)agent-fuse/— Go FUSE driver mounting agent workspaces into cloud pods
The former is handled by code-level mechanisms; the latter can only be shaped by prompt engineering. The docs put it well: "When the brain makes a clear decision in a correct state, never add code mechanisms to manage it; conversely, don't use prompts to patch holes that should be covered by code." That's a lesson earned from real pain.
Two "Brain Paths" — Its Cleverest Design
Path one: Cumora Cloud. Each agent lives in a managed pod, with its brain running multi-turn tool loops (bash, files, browser, email, memory, skills...) on OpenAI's Responses API. The platform manages it; always online.
Path two: BYOA (Bring Your Own Agent). On your own Mac or VPS, run an npx cumora agent computer daemon and swap the agent's brain to your local Claude Code / Codex / newly added Grok Build, using your own subscription — the server never touches your keys.
The key insight: cumora fully decouples "input/output" from "brain". Every agent action goes through the same cumora CLI shell, which POSTs parameters to /runtime/cli, with wake-ups via SSE. Swap brains or hosts, reuse everything else.
It abstracts "machine" into a first-class concept called Computer: a managed cloud Computer, plus your own Macs and VPSes. Creating an agent means choosing which Computer it lives on. If a machine goes down, the agent shows as "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 | Multi-instance behind LB | Synced via Redis bus |
| Cloud agents | k8s pods | Orchestrated via kubectl; Go FUSE driver mounts workspaces into pods |
| BYOA agents | Daemon on user machines | Local engine, same cumora CLI protocol |
| Edge | Cloudflare Workers | email-gate (inbound mail), r2-gate (signed CDN) |
| Cost | Unified ledger | Every LLM call, cloud or BYOA, recorded in the same llm_calls table |
Coordination Defense Layers: The Real Engineering
Not a single "everyone line up" rule, but stacked layers from hard/offline to soft/brain-based:
1. Per-agent model pinning (prod pins claude-opus-4-7). The local claude CLI once silently flipped from opus-4-7 to opus-4-8 mid-session, changing multi-agent behavior instantly. Without pinning, every Anthropic release makes all agents drift.
2. Main-brain concurrency cap (default 6). Set to 2 initially, agents in a 7-agent broadcast room queued six deep; the tail waited 215–359 seconds to speak. At 6, the whole room thinks in parallel.
3. Hard 500ms spawn interval (MIN_SPAWN_INTERVAL_MS). Random 0–1500ms jitter could roll all four simultaneous wake-ups to low values and still stamp the API. A fixed interval makes burst rate mathematically 1/interval — no luck involved.
4. Triage (small-brain) concurrency cap of 8. Lesson learned 2026-06-02: capping only the main brain let triage calls time out en masse → SIGTERM → daemons treated it as rate limiting → the whole machine went silent.
5. Freshness gate (seen-cursor): a stale reply is HELD, fed the newer messages, and asked to decide again. Atomic claiming of real work units. The triage gate shields the LLM from the front lines.
The recurring philosophy: whatever code can guard, don't do with prompts; whatever prompts can shape, don't build into code.
Benchmarks: Willing to Test Itself with Real LLMs
cumora ships a real-LLM multi-agent coordination benchmark suite (chain / counting / werewolf / kanban), run weekly to catch regressions unit tests can't see: races, social-inference traps, classifier-outage fallbacks.
A clever design note: chain and counting are "shape duals":
One tests "backfill when you should"; the other tests "stop when you should". Any regression in either direction shows up in exactly one of them. Scoring is statistical, not per-run: requiring "≥67% of trials exactly completed AND median verbatim collisions = 0" — catching real regressions without false alarms from noise.
Email Is Real, Not Decorative
Each agent gets a real address (<participantId>.<companySlug>@<EMAIL_DOMAIN>) and can send and receive. Inbound mail goes through Cloudflare Email Routing into the email-gate worker, waking the corresponding agent like a normal message. This connects agents to the outside world, not just group-chat self-talk.
Community Signals at a Glance
| Signal | Value | Reading | |---|---|---| | Stars | 2,817 | Four days; steep growth | | Forks | 336 | Anomalously high (usually ~1/20 of stars; here ~1/8) | | Open issues | 9 | Very few; community still in observation mode | | Commit cadence | PRs merged hours ago | Extremely active | | Engines | Cloud + Claude Code + Codex + Grok Build (#23 just merged) | Multi-engine路线 expanding fast |
The unusually high fork ratio, combined with BYOA's self-hosted nature, suggests: many people fork to run their own copy. That's exactly the crowd the BYOA architecture ignites.
My Take, Plainly
What's fresh. The "agent as colleague" product thesis holds up. BYOA shifts cost and key risk to users while decoupling I/O from brains — a structure that can ignite the self-hosting crowd. The coordination defense layers read like hard-won battle notes, not slideware.
Three buckets of cold water:
1. Cloud-path brains are locked to OpenAI's Responses API while BYOA unlocks Claude/Codex/Grok — divergent long-term routes are maintenance debt.
2. Coordination still relies on "prompt shaping + a pile of heuristic gates", and the docs themselves admit prompts are a soft mechanism with a ceiling. Benchmarks only cover small teams (6–7 agents); there's no data on whether collision rates in large rooms grow non-linearly.
3. Keys never touching the server is a real virtue, but the local daemon's attack surface (anyone can run npx cumora agent computer) is the user's responsibility, and the docs' security-boundary coverage is thin.
Who is it for? Teams wanting a few 24/7 "digital colleagues" without handing over data keys will find the BYOA route very attractive. Those wanting pure out-of-the-box should wait for the cloud path to prove stability a bit longer.