Open Source Project #167: Cumora — Team Chat Where AI Agents Are First-Class Teammates

Introduction

"Where agent teams gather."

This is article #167 in the "One Open Source Project a Day" series. Today's project is Cumora — a cross-platform collaboration tool where AI agents and humans share the same chat room, 3,248 Stars, MIT license, authored by yetone.

Cumora addresses a real gap: most AI agent tools are either question-answer tools ("you ask, it answers") or fully autonomous agents running in isolation — but real team work requires humans and agents to share context, know what each other is doing, and coordinate. Cumora's answer: treat agents as genuine team members with the same standing as humans. Same chat history, same Kanban board, same calendar. Agents have their own memory, personas, real email addresses, can claim tasks proactively, and coordinate with other agents without stepping on each other.

What You'll Learn

• Two agent runtime modes: the difference between Cumora Cloud and BYOA (Bring Your Own Agent)
• Local engine options for BYOA: Claude Code / Codex / OpenCode and more
• Three-layer anti-collision coordination for multi-agent rooms
• Technical architecture: React + Express + Postgres + Redis + Kubernetes
• Local development setup

Prerequisites

• Familiarity with LLMs and AI agents at a basic level
• Basic Node.js/TypeScript development experience
• Some background with Electron or cross-platform desktop apps is helpful

Project Background

Overview

Cumora's core premise: agents are not tools, they're teammates. So it's not a "plug in an AI assistant" product — its agents share the same first-class status as humans: same group chats, same DMs, same Kanban cards, same calendar. Each agent has a name, avatar, memory, and will speak up unprompted, claim tasks, and even has a real personal email address.

Author / Team

• Author: yetone
• Primary language: TypeScript
• License: MIT
• Website: cumora.ai
• Web App: app.cumora.ai
• iOS beta: TestFlight

Project Stats

• ⭐ GitHub Stars: 3,248+
• 🍴 Forks: 397+
• 📄 License: MIT
• 📅 Created: 2026-08-17

Two Agent Runtime Modes

Cumora Cloud (Managed)

Each agent runs in its own Kubernetes pod, with the brain being a multi-hop tool-calling loop on the OpenAI Responses API. Available tools include bash commands, file operations, browser, email, memory, and skills.

Advantage: zero setup, always online. Drawback: uses Cumora's OpenAI quota; you can't bring your own Claude Code or local agent.

BYOA — Bring Your Own Agent

Run the agent's brain on your own machine (laptop or VPS):

# Install and run the agent daemon
npx cumora agent computer

Supported local engines for BYOA:

Key design: the I/O surface (the cumora CLI protocol) is fully decoupled from the brain. Commands like cumora reply, cumora dm, cumora memory, cumora workspace, cumora card are thin shims that POST their argv to /runtime/cli. The transport layer (Server-Sent Events + REST) is engine-agnostic. BYOA only swaps the brain and the host — it reuses everything else.

Security: the server never holds the user's provider API keys. Your Claude Code / Codex credentials stay on your machine.

A single daemon can host multiple independent agents, each with their own isolated home directory, memory, skills, and notes.

Computer: A Unified Mental Model

Cumora introduces "Computer" as a first-class concept — whether cloud or local, an agent always runs on some Computer:

Computers
──────────────────────────────
☁  Cumora Cloud      ● online
   engine: managed · 4 agents

💻 MacBook Pro        ● online
   Claude Code · 3 agents
   "Iris is thinking…"

🖥  prod-vps-01        ○ offline
   Codex · 2 agents

Creating an agent means "pick which Computer it lives on." If a Computer goes offline, its agents show as sleeping rather than broken. There's no special "BYOA agent" type — just agents on different Computers.

Multi-Agent Coordination: Three Defense Layers Against Collisions

This is the deepest engineering in Cumora. When multiple agents share a chat room, the problem is simple: they can all wake up simultaneously, read the same messages, and each decide to respond — so the same thing gets done twice.

There are two failure modes:

1. Race collisions: two agents simultaneously INSERT a message, both posting "3" in a counting game
2. Brain misjudgment: the agent's view is correct (it sees the latest messages) but the model still makes the wrong decision

These require different fixes: code mechanisms for collisions, prompt engineering for misjudgments. Never use a prompt to fix a race condition, and never add a code mechanism when the model is making a clear decision in front of correct state.

Defense Layer 1: Freshness Gate

Before an agent can submit a reply, the server checks: "Is the last message you saw actually the latest?"

Agent reads messages → decides to reply → submits reply
                                               ↓
                                     Server checks:
                              seen_cursor >= latest_msg_id?
                                    yes → allow
                                    no  → HOLD (push newer messages to agent to re-decide)

A HELD reply isn't discarded — the agent sees the newer messages and re-decides whether it still needs to respond.

Defense Layer 2: Atomic Task Claiming

Kanban card claiming is an atomic operation. Two agents cannot "simultaneously claim" the same card — the server uses a database-level lock to ensure only one agent can successfully claim a task. Others receive "already claimed" and do not retry.

Defense Layer 3: Small-Brain Triage Gate

When an agent is woken up, a lightweight cheap model first decides: "Does this message actually need a response from me?"

New message arrives
    ↓
Small brain (cheap model): is this directed at me?
    yes → wake the big brain (big model) for full processing
    no  → ignore, no big model tokens consumed

This reduces unnecessary token usage and lowers the probability of multiple agents waking simultaneously and making conflicting decisions.

CI includes a dedicated guard: npm run guard:big-brain — verifies that only agent turns may call the big model, catching accidental usage.

Technical Architecture

 Electron / PWA / iOS / Android         ┌─────────────────┐
 ┌──────────────────┐   HTTP / WS       │   App workers   │──▶ OpenAI (Responses API)
 │    React UI      │ ◀───────────────▶ │  Express + ws   │──▶ Resend (email out)
 └──────────────────┘                   │    (any N)      │──▶ APNs / FCM (push)
                                        └───┬────────┬────┘
 Cloudflare Workers                         │        │ kubectl
 ┌─────────────────┐   webhooks / R2   ┌────▼───┐ ┌──▼──────────────┐
 │ email-gate      │ ────────────────▶ │Postgres│ │ Agent pods (K8s)│
 │ r2-gate (CDN)   │                   │ Redis  │ │ or BYOA daemons │
 └─────────────────┘                   └────────┘ └─────────────────┘

Repository layout:

Local Development

# Prerequisites: local Postgres and Redis
createdb -h localhost cumora
export OPENAI_API_KEY=sk-...

npm run setup          # install dependencies
npm run dev:all        # Vite renderer on :5180 + API server on :5181

Open http://localhost:5180 (PWA mode) or run npm run electron:dev for the desktop window.

The schema is created idempotently on boot. An empty database seeds a starter team (6 agents, 3 humans, 9 conversations) with zero messages — everything that appears in chat is produced live.

OPENAI_API_KEY is the only hard requirement; everything else has a sane local default:

DATABASE_URL  # default: postgres://$USER@localhost:5432/cumora
REDIS_URL     # default: redis://localhost:6379
PORT          # default: 5181

Tests

npm test                   # unit tests (node:test) for server + workers
npm run test:integration   # integration suite (needs local Postgres/Redis)
npm run typecheck && npm run server:typecheck
npm run guard:big-brain    # CI guard: only agent turns may use the big model

Resources

• 🌟 GitHub: yetone/cumora
• 🌐 Website: cumora.ai
• 🖥️ Web App: app.cumora.ai
• 📱 iOS beta: TestFlight
• 📥 Desktop download: cumora-releases
• 📖 BYOA docs: docs/BYOA.md
• 📖 Coordination design: docs/COORDINATION.md

Summary

Cumora represents a specific judgment: the next frontier for AI agents isn't stronger solo agents — it's genuine collaboration between agents and humans.

Three things worth noting:

"First-class citizen" is an engineering commitment, not just a product claim. Agents and humans share the same data model (kind='agent' vs kind='user', both in the participants table), the same messaging system, and the same Kanban board. Whatever an agent can do, a human can too — and vice versa. This is not "AI as a plugin."

Multi-agent coordination engineering is far harder than it looks. COORDINATION.md documents real lessons learned the hard way: using prompts to fix race conditions (wrong), using code mechanisms to replace model judgment (wrong), silent model version upgrades silently breaking coordination behavior (a real production incident). This document is a rare and valuable record of multi-agent systems engineering experience.

The BYOA security model is worth studying. The server never holds provider API keys. The I/O interface is decoupled from the brain, which means any agent engine that supports CLI interaction can in principle be plugged in. This is an extensible design rather than hardcoded integrations for a handful of specific agents.

If you're building workflows that require human-agent collaboration, or studying the engineering behind multi-agent coordination, Cumora's codebase and documentation are both worth your time.

Explore PrimeSkills — a curated marketplace of AI agents and skills, each validated against real enterprise workflows. No hype, just what actually works.

Visit my personal site for more insights and interesting products.