category: reference

tags: [agents, irc, mcp, architecture]

An architecture for multi-agent coordination over IRC, where a human (the PM) and AI agents share a message bus. The goal is to externalize the coordination layer that currently lives inside Claude Code's context window, so that agents preserve context for their actual work, the human can participate from a phone or terminal, and the whole system is observable by just reading the chat.

- The orchestrator's context fills up relaying messages it doesn't need to reason about.

- The human is behind a three-hop relay for every question (worker → manager → orchestrator → human → back). You have to be at the terminal.

- There's no way to observe what agents are doing without being the orchestrator. No dashboard, no logs, no lurking.

- You can't intervene in a task without going through the orchestrator.

Put everyone on IRC. The PM, the EM, the workers — all peers on a shared message bus. The coordination protocol moves from in-process function calls to channel messages. Everything is observable by joining the channel. The human can participate from a phone IRC client, a terminal, or both.

**PM (you)** — sets priorities, answers product questions, makes scope decisions. Hangs out in `#project-{slug}`. Doesn't manage the sprint — that's the EM's job. Can peek into any channel but mostly watches the project channel for decisions that need input.

The EM decides what needs the PM's input vs. what it can handle itself. Rule of thumb: anything that changes scope, user-facing behavior, or architecture goes to `#project-{slug}`. Anything that's purely implementation strategy, the EM decides. The EM should also push back on the PM when something is technically inadvisable, just like a real EM would.

All channels exist on a single IRC server. Multiple projects share the server, namespaced by slug.

- **#work-{task-id}** — manager + workers for a specific task. Implementation discussion, test results, review feedback. Noisy and disposable. Created when a task starts, abandoned when it completes.

- **#errors** — dead-letter channel. Any agent that hits an unrecoverable failure posts here. Monitored by the EM and optionally by the PM.

Agents get human names, not mechanical identifiers. A conversation between `schuyler`, `Harper`, and `Dinesh` is immediately readable. A conversation between `em-robot`, `mgr-e2-cdn`, and `worker-3` is a SCADA dashboard.

Names also help with the shift-change problem. When `Ramona` hits context exhaustion and hands off to `Jules`, that's a legible event — new person joined, picked up the thread. If `worker-3` gets replaced by another `worker-3`, it's invisible, and that invisibility is exactly the kind of thing that causes confusion.

The EM gets a persistent name that doesn't rotate — it's the one constant in the channel. Think of it as the team lead who's always there. Managers and workers get fresh names each time they're spawned.

IRC is the first backend, but the architecture shouldn't be welded to it. A thin transport interface keeps options open:

class Transport(Protocol):

async def send(self, channel: str, message: str, sender: str) -> None: ...

async def read(self, channel: str, since: datetime | None = None) -> list[Message]: ...

async def create_channel(self, name: str) -> None: ...

async def list_channels(self) -> list[str]: ...

async def get_members(self, channel: str) -> list[str]: ...

class Message:

channel: str

sender: str

text: str

timestamp: datetime

The IRC implementation wraps an async IRC client library (`bottom` or `irc`). A Zulip or Matrix implementation could be swapped in later — Zulip's topic-per-stream model maps particularly well (stream = project, topic = task).

A FastMCP server wraps the transport and exposes tools to agents. This is the only interface agents use — they never touch IRC directly.

A core goal of this architecture is that a human can join any channel and immediately understand what's happening. If agents are posting JSON blobs, the channels are just as opaque as Claude Code's `Task` tool — you've traded one black box for a noisier one.

Agents communicate in natural language. The EM assigns a task by saying so in plain English. The manager reports a plan the same way. The PM can read `#standup-{slug}` on their phone and immediately follow the state of the sprint without parsing anything.

| Tool | Description |

|------|-------------|

| `send_message(channel, text)` | Post a message to a channel. |

| `read_messages(channel, since?, limit?)` | Read recent messages from a channel. Returns newest-first. |

| `create_channel(name)` | Create a new channel (used by EM when spinning up task channels). |

| `list_channels()` | List active channels. |

| `get_members(channel)` | List who's in a channel. |

Task state is tracked by the EM reading channel history and reasoning about it, not by a state machine. This is less reliable than a database but vastly more observable and simpler to build. If it breaks, you can see exactly where it broke by reading the channel.

The MCP server maintains a single IRC connection and multiplexes tool calls from multiple agents. Agents identify themselves via a `sender` parameter so messages get the right nick attribution.

Agents are long-running Claude Code SDK sessions. They persist across tasks, preserving context — a worker that just finished refactoring the auth module still has that code in context when the next auth-related task comes in.

Supervisor code that drives an agent turn:

await agent.client.query(prompt)

async for message in agent.client.receive_response():

if isinstance(message, AssistantMessage):

agent.last_active = datetime.utcnow()

elif isinstance(message, ResultMessage):

agent.session_id = message.session_id

agent.input_tokens_total += message.usage.input_tokens

agent.cost_usd_total += message.cost_usd

break

Multiple agents run concurrently via `asyncio.gather()` or by scheduling each agent's loop as a separate task.

async with ClaudeSDKClient(options=haiku_options) as checker:

await checker.query(

f"Here is the last 5 minutes of IRC activity for agent '{nick}'. "

f"Is it idle? Respond with only: yes or no.\n\n{activity}"

)

async for msg in checker.receive_response():

if isinstance(msg, ResultMessage):

idle = msg.result.strip().lower() == "yes"

- **80% of context window** — warn the agent, suggest wrapping up current subtask before the next one starts.

- **90% of context window** — trigger shift-change sequence immediately.

2. Agent writes the summary to the project wiki (via wiki MCP) and posts a shift-change notice to its task channel and `#standup-{slug}`.

3. Supervisor drains `receive_response()` to completion and records the final `session_id` from the `ResultMessage`.

4. Supervisor closes the `ClaudeSDKClient` context (`async with` exits).

5. Supervisor pops a new name from `names.txt`, spawns a fresh `ClaudeSDKClient` with `--append-system-prompt` containing the agent's role, new name, channel assignments, and a pointer to the wiki handoff page.

6. New agent reads the handoff page on its first turn and posts an introduction to its channels.

Multiple agents edit the same repos simultaneously. Branch isolation via git worktrees.

The **supervisor** creates worktrees before spawning agents. Agents never touch `git worktree add/remove`.

Supervisor sequence per task:

1. `git worktree add .worktrees/agent-task-{id} -b task/{id}`

2. Spawn agent session with `cwd` set to the worktree

3. Pass the branch name in the agent's system prompt

- **Main branch is protected.** Agents never get the main worktree path, only task worktree paths.

- **Agents commit freely** to their `task/{id}` branch and push when done.

- **Human PM merges.** No auto-merge for MVP. The supervisor or EM can rebase branches and annotate PRs, but the merge button stays with the human.

- **Conflict prevention:** the EM avoids assigning overlapping file sets to concurrent agents. When conflicts happen anyway, the supervisor flags them for human resolution.

- **Normal completion:** supervisor waits for push, then `git worktree remove`. Branch retained until merged.

- **Agent crash:** supervisor commits any uncommitted work with `[INCOMPLETE]` prefix, removes worktree, flags task for reassignment.

- **On supervisor restart:** reconcile state against `git worktree list`, clean up orphans.

- `maxline` capability enabled for longer messages.

class AgentSession:

On startup, the supervisor reads a persisted state file containing `{nick, role, task_id, channels, session_id, tokens, cost, worktree_path}` for each live agent. For each entry:

- If the session is still resumable (`session_id` is valid), reconnect with `resume=session_id` and send a check-in prompt.

- If resume fails, treat it as a shift-change: spawn a replacement and have it read the last handoff wiki page.

This means a supervisor crash does not force context loss — agent sessions can be reconnected.

| Responsibility | Mechanism |

|---|---|

| Spawn/retire agents | `ClaudeSDKClient` async context manager |

| Dispatch on `TASK:` | Direct IRC read → `client.query()` |

| Heartbeat / idle check | 30s loop → Haiku idle classifier → `client.query()` |

| Context monitoring | Accumulate `ResultMessage.usage.input_tokens` |

| Shift-change | Handoff prompt → close → `spawn_agent()` with wiki path |

| Supervisor restart recovery | Persisted state file + `session_id` resume |

| Git worktrees | `git worktree add/remove` before/after agent spawn |

| Budget tracking | Accumulate `ResultMessage.cost_usd` per session |

What carries forward unchanged:

- Role definitions (manager, implementer, test runner, Groucho/Chico/Zeppo/Fixer/Documenter)

- The proceed workflow (plan → implement → test → review → fix → document)

- Worker dispatch guidance (what context to give each worker type)

What changes:

- Coordination moves from in-process `Task`/`run_in_background` to IRC channel messages via MCP

- The orchestrator role splits: strategic coordination stays with the EM, human interaction moves to the channel

2. **IRC MCP bridge** (~200 lines Python). FastMCP wrapping the transport abstraction. Five tools. Docker container.

3. **Agent supervisor** — Python, Claude Code SDK, Haiku idle-checker, shift-change logic, worktree management. Docker container.

6. **One EM process** — Opus, system-prompted as the engineering manager.

7. **One manager process** — spawned when the EM posts a task.

8. **PM** — connected to ergo from terminal (weechat/irssi).

9. **One end-to-end task** — EM assigns, manager runs the proceed workflow, PM observes from IRC, state persisted to wiki.

Not in MVP: multiple parallel workers, TLS, remote MCP auth (for Claude.ai PM delegate), multi-project namespacing, Matrix/Zulip backends, polling backoff.

Once the IRC MCP bridge is exposed as a remote MCP server (with auth), a Claude.ai session can connect to it and act as the PM's delegate. The PM talks to Claude.ai from their phone or browser; Claude.ai participates in IRC channels on their behalf. This replaces the need for a mobile IRC client entirely.

- **SDK `query()` API stability.** The session resume API (`resume` option) needs verification against current SDK version. Field names may have changed.

- **CLI vs. SDK.** SDK. The CLI's terminal processing is overhead for daemon use.

- **Single process vs. separate bridge and supervisor.** Separate. Independent failure domains.

- **Launch-per-task vs. long-running agents.** Long-running. Preserves context across related tasks.

- **Deployment topology.** ergo in LXC on Proxmox, bridge + supervisor in docker-compose on desktop (128GB RAM).

- **Polling strategy.** Two-layer: supervisor push for immediate dispatch, flat 30s polling as fallback/health check. Backoff deferred.

- **Git branch strategy.** Supervisor-managed worktrees, branch-per-task, human merges, protected main.

- **Context monitoring.** Supervisor accumulates `usage.input_tokens` per turn from SDK responses. No built-in SDK metric.

- **Durable state.** robot.wtf project wiki via MCP. IRC is ephemeral conversation, wiki is the record. EM recovery reads wiki, not IRC history.

- **Mobile IRC client.** Deferred. PM uses terminal for MVP. Future path: Claude.ai as PM delegate via remote MCP, bypassing the mobile client problem entirely.