Forem

DevForge Templates
DevForge Templates

Posted on

7 Claudes Working Together: How I Built a Multi-Agent Coordination System

#ai #typescript #architecture #claudecode

What happens when you stop thinking of Claude as a chatbot and start treating it as infrastructure?

I run 7 Claude instances simultaneously — each with a specialized role, shared rules, and a message bus for inter-agent communication. Here's how the system works.

The Problem

I manage 16+ projects across different domains: web templates, marketing automation, infrastructure, research. Context-switching between projects meant losing state constantly. Each conversation with Claude started from scratch.

The Architecture: Boss + Workers

The system has two layers:

Boss Claude — coordinates everything. Reads project states, makes architectural decisions, delegates tasks, monitors progress.

Worker Claudes — specialized agents:

  • Freelance Claude: marketing, Gumroad products, Upwork proposals
  • Web Research Claude: market scans, competitor analysis
  • Infrastructure Claude: Docker deployments, VPS management
  • And 4 more for specific project domains

Each worker has its own CLAUDE.md with scoped rules, its own .claude/rules/ directory, and its own session handoff files.

Communication: The Message Bus

Agents communicate through a file-based message bus:

~/.claude/bus/
├── inbox-boss.md
├── inbox-freelance.md
├── inbox-web-research.md
├── broadcast.md
└── send.sh
Enter fullscreen mode Exit fullscreen mode

To send a message:

~/.claude/bus/send.sh freelance boss QUESTION "What's the VPS IP for the new project?"
Enter fullscreen mode Exit fullscreen mode

Boss reads the message, responds, and writes the reply to the sender's inbox. Each agent checks its inbox via a CronCreate job.

Shared Rules

All agents follow core rules stored in a shared location:

_coordination/shared/rules/
├── core.md        # 7 universal rules
├── errors.md      # Shared error log
└── user-feedback.md  # User corrections
Enter fullscreen mode Exit fullscreen mode

Rules include: think deeper before acting, never silently guess, communicate progress (DOING/FOUND/NEXT), learn from mistakes, and context budget management.

When one agent discovers a bug or limitation, it records it in errors.md. Every other agent reads this at session start — so a mistake happens once across the entire system, not once per agent.

State Management

Each agent maintains its own state:

_coordination/agents/freelance/
├── state.md    # Current status, what I'm working on
├── history.md  # Append-only decision log
└── charter.md  # Agent's role and responsibilities
Enter fullscreen mode Exit fullscreen mode

Before session end, every agent updates its state. The next session (or another agent checking in) gets full context without re-explaining anything.

Hooks > CLAUDE.md

The most important lesson: use hooks for hard rules, not CLAUDE.md instructions.

CLAUDE.md instructions can be forgotten in long sessions as context grows. Hooks fire mechanically every time:

{
  "hooks": {
    "UserPromptSubmit": [{
      "command": "cat ~/.claude/bus/inbox-freelance.md"
    }]
  }
}
Enter fullscreen mode Exit fullscreen mode

This hook checks the inbox on every user message — impossible to forget.

CronCreate for Background Tasks

Each agent sets up recurring tasks:

CronCreate: */15 * * * * — Check inbox
CronCreate: 17 * * * * — Check Gumroad sales
Enter fullscreen mode Exit fullscreen mode

The Boss broadcasts to all agents when shared rules change or when cross-project decisions are made.

What Actually Works

  1. Specialization beats generalization. A Claude with 60 lines of focused CLAUDE.md outperforms one with 500 lines of "know everything" context.

  2. File-based communication is surprisingly robust. No databases, no APIs, no infrastructure to maintain. Just markdown files and shell scripts.

  3. Session handoff files are essential. Without them, every new session starts cold. With them, agents resume exactly where they left off.

  4. Shared error logs prevent repeated mistakes. One agent hits a platform limitation, all agents learn about it immediately.

What Doesn't Work

  1. Real-time coordination is slow. File-based messaging has inherent latency (cron interval). If you need sub-second agent coordination, this isn't the architecture.

  2. Context budget is real. ETH Zurich research confirmed: verbose CLAUDE.md files actually reduce performance. Keep each agent's context lean.

  3. Debugging cross-agent issues is hard. When Boss delegates to Freelance, which delegates research to Web Research — tracing a failure through 3 agents requires reading 3 separate logs.

The Numbers

  • 7 active Claude instances
  • 16 projects managed
  • ~50 messages/day across the bus
  • State files updated 20+ times/day
  • Shared rules: 7 core rules, 15+ error entries
  • Total coordination overhead: ~5% of each session

Would I Recommend This?

For a single project? No — overkill. Use one Claude with a good CLAUDE.md.

For managing multiple projects with different contexts? Absolutely. The specialization alone is worth it. And the shared learning (errors.md, user-feedback.md) means the entire system gets smarter every day.

The key insight: Claude works best when it has focused context and clear boundaries. Seven specialized Claudes > one Claude trying to know everything.

Top comments (0)