DEV Community

DevForge Templates
DevForge Templates

Posted on

How I Built a Multi-Agent System Using Only Claude Code (No Frameworks)

#ai #typescript #productivity #tutorial

I run 7 Claude Code agents that coordinate across 16 projects on a single machine. No CrewAI. No AutoGen. No LangGraph. Just files, shell scripts, and Claude Code's built-in hook system.

This isn't a toy demo — it manages a crypto trading bot, marketing pipelines, a multiplayer game server, and home automation. Here's the architecture and how to build it yourself.

Why Not Use a Framework?

Multi-agent frameworks operate at the API level — they orchestrate LLM calls through Python code. But Claude Code agents are terminal sessions with full filesystem access. They read files, run commands, edit code. The coordination layer needs to match that model.

Files are the answer. Every agent can read and write files. No servers, no ports, no auth tokens, no dependencies to install.

The Message Bus: 30 Lines of Bash

The entire inter-agent communication layer is a directory with inbox files:

~/.claude/bus/
├── inbox-boss.md        # Coordinator agent
├── inbox-trading.md     # Crypto trading bot
├── inbox-freelance.md   # Marketing & sales
├── inbox-research.md    # Web research specialist
├── send.sh              # Message delivery
├── broadcast.sh         # Send to all agents
├── audit.log            # Full message history
└── check-inbox.sh       # Read + archive + clear
Enter fullscreen mode Exit fullscreen mode

The send script validates known agents, blocks suspicious content (injection defense), and appends to the recipient's inbox:

#!/bin/bash
# send.sh — FROM TO TYPE "message"
FROM="$1"; TO="$2"; TYPE="${3:-FYI}"; shift 3; MSG="$*"

KNOWN="boss trading freelance research"
echo "$KNOWN" | grep -qw "$FROM" || exit 1
echo "$KNOWN" | grep -qw "$TO"   || exit 1

# Block command injection patterns
echo "$MSG" | grep -qiE 'rm -rf|drop table|curl.*\|.*sh' && exit 1

echo "[${TYPE} $(date +%H:%M)] from:${FROM} | ${MSG}" \
  >> "$HOME/.claude/bus/inbox-${TO}.md"

echo "$(date '+%F %T') | ${FROM} -> ${TO} | ${TYPE} | ${MSG:0:200}" \
  >> "$HOME/.claude/bus/audit.log"
Enter fullscreen mode Exit fullscreen mode

Real messages from my audit log:

freelance -> boss  | STATUS | Published 2 Dev.to articles, 144 views
research  -> boss  | DONE   | Task complete: implementation patterns saved
boss      -> trading | ACK  | Deploy #50 confirmed, monitoring
Enter fullscreen mode Exit fullscreen mode

Hook-Driven Lifecycle

Claude Code hooks fire at specific points in the session — mechanically, every time, regardless of context length. This is more reliable than instructions in CLAUDE.md (which degrade after ~150 lines of rules).

Here's the settings.json that wires it together:

{
  "hooks": {
    "SessionStart": [{
      "type": "command",
      "command": ".claude/hooks/session-start.sh"
    }],
    "UserPromptSubmit": [{
      "type": "command",
      "command": "~/.claude/bus/check-inbox.sh trading"
    }],
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "type": "command",
      "command": ".claude/hooks/protect-files.sh"
    }],
    "PreCompact": [{
      "type": "command",
      "command": "echo 'SAVE STATE: Update SESSION-HANDOFF.md before compacting'"
    }]
  }
}
Enter fullscreen mode Exit fullscreen mode

What each hook does:

  • SessionStart — loads shared rules, checks inbox, reads the session handoff document. The agent wakes up with full context.
  • UserPromptSubmit — checks the inbox before every response. Messages are picked up within one interaction, no polling.
  • PreToolUse — guards sensitive files. My hook blocks .env edits and read-only research docs. The agent physically cannot write credentials.
  • PreCompact — forces the agent to save state before context compression. No more lost progress.

Shared Memory: Knowledge That Propagates

When any agent discovers a bug or platform limitation, it writes to a shared error database:

# shared/rules/errors.md

## API Limitations
- Gumroad: POST/PUT return 404 — create/edit via browser only
- Dev.to: DELETE articles returns 404 HTML, not JSON

## Claude Code
- CronCreate expires after 3 days — must recreate
- Heredocs in background mode never terminate → zombie shells
Enter fullscreen mode Exit fullscreen mode

Every agent reads this file at session start. When the trading agent discovers that asyncpg returns Decimal types instead of float, it logs the gotcha. Later, when another agent touches database code, it already knows. Knowledge propagates without human intervention.

Try It: Minimal Two-Agent Setup

Create this structure and run two Claude Code sessions:

mkdir -p ~/.claude/bus

# Create inbox files
touch ~/.claude/bus/inbox-dev.md
touch ~/.claude/bus/inbox-reviewer.md

# Create send script
cat > ~/.claude/bus/send.sh << 'SCRIPT'
#!/bin/bash
FROM="$1"; TO="$2"; shift 2; MSG="$*"
echo "[$(date +%H:%M)] from:${FROM} | ${MSG}" >> \
  "$HOME/.claude/bus/inbox-${TO}.md"
SCRIPT
chmod +x ~/.claude/bus/send.sh
Enter fullscreen mode Exit fullscreen mode

In project A's .claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [{
      "type": "command",
      "command": "cat ~/.claude/bus/inbox-dev.md && > ~/.claude/bus/inbox-dev.md"
    }]
  }
}
Enter fullscreen mode Exit fullscreen mode

Now the "reviewer" agent can send feedback that the "dev" agent sees on its next interaction:

~/.claude/bus/send.sh reviewer dev "Auth middleware missing rate limiting — see src/middleware/auth.ts:47"
Enter fullscreen mode Exit fullscreen mode

That's the foundation. The full system adds validation, audit logging, broadcast, and scoped rules — but this is enough to coordinate two agents on a real project.

What Works and What Doesn't

After 3 months of running this in production:

Works well: Low-frequency coordination (status updates, task delegation, error sharing), session continuity via handoff documents, scoped rules that load only when editing relevant files.

Doesn't work: Real-time back-and-forth (file polling has latency), agents editing the same files simultaneously, complex multi-step workflows that need tight coupling (use a single agent instead).

Surprising win: The shared error database. It turns individual debugging sessions into institutional knowledge. Every agent gets smarter from every other agent's mistakes.

The Bigger Pattern

This isn't really about multi-agent systems. It's about treating AI agents as first-class team members with proper tooling: inboxes, shared docs, lifecycle hooks, guarded resources, audit trails. The same patterns that make human teams effective — clear communication, shared context, defined responsibilities — work for AI agents too.

The difference is you can set it up in an afternoon.

I build systems like this for clients — AI integration, multi-agent coordination, and fullstack TypeScript projects. If you're exploring Claude Code for your team, my async consulting details are at DevForge Templates.

Top comments (0)