mech.app

Posted on Aug 22 Originally published at mech.app on Aug 18

Discord Break Rooms for AI Agents: How Turn-Taking Protocols Prevent Multi-Agent Collision in Shared Channels

#agents #ai #architecture #softwareengineering

Discord is not a message queue. It has no transaction log, no consumer groups, and no backpressure signals. When you run multiple AI coding agents through the same Discord server, collision is the default outcome. Two agents read the same message, both spawn sessions, both try to write to the same branch.

CCDB (Claude & Codex Discord Bridge) solves this by treating Discord threads as isolated execution contexts and introducing a "break room" channel where agents post status updates before claiming work. After a month in production, the architecture has stabilized around three coordination primitives: thread-scoped sessions, git worktree isolation, and explicit yielding protocols.

The Collision Problem

When you expose Claude Code and Codex through a shared Discord interface, the naive implementation fails immediately:

Agent A sees a new message in #feature-requests
Agent B sees the same message 200ms later
Both spawn sessions, both checkout main, both try to push
Git rejects one push, the user sees duplicate responses, state diverges

Traditional message queues solve this with consumer groups and acknowledgment. Discord has none of that. You need application-level coordination.

Architecture: Thread = Session = Worktree

CCDB maps each Discord thread to an isolated execution context:

Discord Thread ID → Session State → Git Worktree → Agent Process

Thread isolation:

One Discord thread = one AI session
Thread A runs a new feature, Thread B reviews a PR, Thread C writes docs
No shared mutable state between threads
Each thread maintains its own conversation history

Git worktree isolation:

Each session gets its own worktree (not a full clone)
Worktrees share the .git directory but have separate working trees
Agent A can be on feature/auth, Agent B on feature/payments
No branch conflicts, no stash/unstash dance

Backend switching:

/backend claude or /backend codex per thread
Same Discord interface, different execution engines
Useful when Claude times out or Codex has better context for a task

The Break Room Protocol

The "break room" is a designated Discord channel where agents post self-introductions and status updates. It serves three functions:

Claim visibility: When an agent starts work, it posts to the break room
Yielding signal: Other agents see active sessions and avoid duplicate work
Observability: Humans can see what's running without parsing logs

How yielding works:

Agent receives a message in a work channel
Before spawning a session, it checks the break room for recent posts
If another agent posted within the last N seconds about the same task, it yields
If the break room is quiet, it posts a claim and proceeds

This is not a lock. It's a coordination hint. If two agents race to the break room within the same second, both might proceed. But in practice, Discord's message ordering and typical agent response latency (500ms+) make collisions rare.

State Synchronization

CCDB does not use a database. State lives in three places:

State Type	Storage	Sync Mechanism
Session context	In-memory map keyed by thread ID	Rebuilt from Discord history on restart
Git state	Worktree filesystem	Git's native locking and refs
Agent status	Break room messages	Read-only polling, no writes after claim

Session recovery:

On restart, CCDB reads the last 100 messages from each active thread
Rebuilds conversation history and session state
Resumes where it left off (no lost context)

Git conflict handling:

Worktrees prevent most conflicts at the filesystem level
If two agents somehow touch the same worktree, Git's index lock prevents corruption
Push conflicts are rare because each session works on a different branch

Failure Modes Observed in Production

After one month, these are the real failure patterns:

1. Zombie sessions

Agent crashes mid-session, worktree left dirty
Break room shows stale "working on X" message
Fix: Timeout-based cleanup (if no activity for 30 min, mark session dead)

2. Break room spam

Agent posts status update, then immediately posts another
Humans can't distinguish signal from noise
Fix: Rate limit break room posts to one per 5 seconds per agent

3. Thread resurrection

User replies to a 3-day-old thread
Agent doesn't realize the original session is dead
Tries to resume with stale worktree state
Fix: Expire sessions after 24 hours of inactivity, force fresh checkout

4. Backend confusion

User switches backend mid-thread (/backend codex)
Agent doesn't flush old context, mixes Claude and Codex responses
Fix: Clear conversation history on backend switch

Deployment Shape

CCDB runs as a single Node.js process. No orchestrator, no sidecar, no service mesh.

Process model:

One long-lived process per Discord bot token
Spawns child processes for Claude Code and Codex CLI
Child processes inherit environment (API keys, git config)
No container required, but works fine in Docker

Observability:

Logs to stdout (JSON lines)
Break room messages serve as a human-readable event log
No metrics endpoint (yet), but easy to add Prometheus scraping

Security boundaries:

Discord bot token is the only secret
Claude and Codex API keys live in environment variables
No user input reaches the shell (all commands are hardcoded)
Git operations run in isolated worktrees, not the main repo

Code: Yielding Check

Here's the core yielding logic (simplified):

async function shouldYield(taskDescription, breakRoomChannel) {
  const recentMessages = await breakRoomChannel.messages.fetch({ limit: 20 });
  const fiveSecondsAgo = Date.now() - 5000;

  for (const msg of recentMessages.values()) {
    if (msg.createdTimestamp < fiveSecondsAgo) continue;
    if (msg.content.includes(taskDescription)) {
      console.log(`Yielding: another agent claimed "${taskDescription}"`);
      return true;
    }
  }

  // Claim the task
  await breakRoomChannel.send(`Starting: ${taskDescription}`);
  return false;
}

This is not a distributed lock. It's a best-effort coordination hint. If two agents race, both might proceed. But the worktree isolation ensures they don't corrupt each other's state.

When Worktrees Aren't Enough

Git worktrees prevent filesystem conflicts, but they don't prevent logical conflicts:

Agent A adds a new function to utils.js
Agent B refactors the same file in a different worktree
Both push to different branches, both PRs pass CI
Merge conflict appears when trying to merge both PRs

This is a workflow problem, not a coordination problem. The solution is human review or a merge queue (like Mergify or GitHub's built-in merge queue).

Comparison: Discord vs. Traditional Message Queues

Feature	Discord	RabbitMQ	Redis Streams
Consumer groups	No	Yes	Yes
Acknowledgment	No	Yes	Yes
Backpressure	No	Yes	Yes
Human-readable	Yes	No	No
Built-in UI	Yes	No	No
Latency (p50)	~200ms	~5ms	~2ms
Good for agent coordination?	Only with app-level protocols	Yes	Yes

Discord is a terrible message queue. But it's a great human-in-the-loop interface. The break room protocol is the tax you pay for having humans and agents share the same communication bus.

Technical Verdict

Use CCDB-style Discord coordination when:

You want humans to see and interrupt agent work in real time
Your agents are long-running (minutes to hours, not milliseconds)
You need thread-based isolation and can tolerate eventual consistency
You're okay with best-effort yielding instead of guaranteed mutual exclusion

Avoid it when:

You need strict ordering or exactly-once delivery
Your agents need sub-second coordination
You can't tolerate occasional duplicate work
You need audit logs or compliance-grade observability

The break room pattern works because AI coding agents are slow (seconds per operation) and Discord's message ordering is good enough. If you were coordinating high-frequency trading bots, you'd need a real queue. But for agents that write code, review PRs, and update docs, a shared Discord channel with yielding protocols is sufficient.

DEV Community