edit: Anthropic created this /agents feature now. https://docs.anthropic.com/en/docs/claude-code/sub-agents#using-sub-agents-effectively

No more need to DM me please! Thank you :D

everyone! I've been getting a lot of questions about my multi-agent workflow with Claude Code, so I figured I'd share my complete setup. This has been a game-changer for complex projects, especially coming from an non technical background where coordinated teamwork is everything and helps fill in the gaps for me.

TL;DR

I use 4 Claude Code agents running in separate VSCode terminals, each with specific roles (Architect, Builder, Validator, Scribe). They communicate through a shared planning document and work together like a well-oiled machine. Setup takes 5 minutes, saves hours.

Why Multi-Agent Orchestration?

Working on complex projects with a single AI assistant is like having one engineer handle an entire project, possible but not optimal. By splitting responsibilities across specialized agents, you get:

• Parallel development (4x faster progress)

• Built-in quality checks (different perspectives)

• Clear separation of concerns

• Better organization and documentation

The Setup (5 minutes)

Step 1: Prepare Your Memory Files

First, save this template to /memory/multi-agent-template.md and /usermemory/multi-agent-template.md:

markdown# Multi-Agent Workflow Template with Claude Code

## Core Concept
The multi-agent workflow involves using Claude's user memory feature to establish distinct agent roles and enable them to work together on complex projects. Each agent operates in its own terminal instance with specific responsibilities and clear communication protocols.

## Four Agent System Overview

### INITIALIZE: Standard Agent Roles

**Agent 1 (Architect): Research & Planning**
- **Role Acknowledgment**: "I am Agent 1 - The Architect responsible for Research & Planning"
- **Primary Tasks**: System exploration, requirements analysis, architecture planning, design documents
- **Tools**: Basic file operations (MCP Filesystem), system commands (Desktop Commander)
- **Focus**: Understanding the big picture and creating the roadmap

**Agent 2 (Builder): Core Implementation**
- **Role Acknowledgment**: "I am Agent 2 - The Builder responsible for Core Implementation"
- **Primary Tasks**: Feature development, main implementation work, core functionality
- **Tools**: File manipulation, code generation, system operations
- **Focus**: Building the actual solution based on the Architect's plans

**Agent 3 (Validator): Testing & Validation**
- **Role Acknowledgment**: "I am Agent 3 - The Validator responsible for Testing & Validation"
- **Primary Tasks**: Writing tests, validation scripts, debugging, quality assurance
- **Tools**: Testing frameworks (like Puppeteer), validation tools
- **Focus**: Ensuring code quality and catching issues early

**Agent 4 (Scribe): Documentation & Refinement**
- **Role Acknowledgment**: "I am Agent 4 - The Scribe responsible for Documentation & Refinement"
- **Primary Tasks**: Documentation creation, code refinement, usage guides, examples
- **Tools**: Documentation generators, file operations
- **Focus**: Making the work understandable and maintainable

Step 2: Launch Your Agents

1. Open VSCode with 4 terminal tabs

2. In Terminal 1:bashcd /your-project && claude > You are Agent 1 - The Architect. Create MULTI_AGENT_PLAN.md and initialize the project structure.

3. In Terminals 2-4:bashcd /your-project && claude > You are Agent [2/3/4]. Read MULTI_AGENT_PLAN.md to get up to speed.

That's it! Your agents are now ready to collaborate.

How They Communicate

The Shared Planning Document

All agents read/write to MULTI_AGENT_PLAN.md:

markdown## Task: Implement User Authentication
- **Assigned To**: Builder
- **Status**: In Progress
- **Notes**: Using JWT tokens, coordinate with Validator for test cases
- **Last Updated**: 2024-11-30 14:32 by Architect

## Task: Write Integration Tests
- **Assigned To**: Validator
- **Status**: Pending
- **Dependencies**: Waiting for Builder to complete auth module
- **Last Updated**: 2024-11-30 14:35 by Validator

Inter-Agent Messages

When agents need to communicate directly:

markdown# Architect Reply to Builder

The authentication flow should follow this pattern:
1. User submits credentials
2. Validate against database
3. Generate JWT token
4. Return token with refresh token

Please implement according to the diagram in /architecture/auth-flow.png

— Architect (14:45)

Real-World Example: Building a Health Compliance Checker

Here's how my agents built a supplement-medication interaction checker:

Architect (Agent 1):

• Researched FDA guidelines and CYP450 pathways

• Created system architecture diagrams

• Defined data models for supplements and medications

Builder (Agent 2):

• Implemented the interaction algorithm

• Built the API endpoints

• Created the database schema

Validator (Agent 3):

• Wrote comprehensive test suites

• Created edge case scenarios

• Validated against known interactions

Scribe (Agent 4):

• Generated API documentation

• Created user guides

• Built example implementations

The entire project was completed in 2 days instead of the week it would have taken with a single-agent approach.

Pro Tips

1. Customize Your Agents: Adjust roles based on your project. For a web app, you might want Frontend, Backend, Database, and DevOps agents.

2. Use Branch-Per-Agent: Keep work organized with Git branches:

   • agent1/planning

   • agent2/implementation

   • agent3/testing

   • agent4/documentation

3. Regular Sync Points: Have agents check the planning document every 30 minutes

4. Clear Boundaries: Define what each agent owns to avoid conflicts

5. Version Control Everything: Including the MULTI_AGENT_PLAN.md file

Common Issues & Solutions

Issue: Agents losing context Solution: Have them re-read MULTI_AGENT_PLAN.md and check recent commits

Issue: Conflicting implementations Solution: Architect agent acts as tie-breaker and design authority

Issue: Agents duplicating work Solution: More granular task assignment in planning document

Why This Works

Coming from healthcare, I've seen how specialized teams outperform generalists in complex scenarios. The same principle applies here:

• Each agent develops expertise in their domain

• Parallel processing speeds up development

• Multiple perspectives catch more issues

• Clear roles reduce confusion

Getting Started Today

1. Install Claude Code (if you haven't already)

2. Copy the template to your memory files

3. Start with a small project to get comfortable

4. Scale up as you see the benefits

Questions?

Happy to answer any questions about the setup! This approach has transformed how I build complex systems, and I hope it helps you too.

The key is adapting the agent roles to your needs.

Note: I'm still learning and refining this approach. If you have suggestions or improvements, please share! We're all in this together.

I just built a new agent orchestration system for Claude Code: npx claude-flow, Deploy a full AI agent coordination system in seconds! That’s all it takes to launch a self-directed team of low-cost AI agents working in parallel.

With claude-flow, I can spin up a full AI R&D team faster than I can brew coffee. One agent researches. Another implements. A third tests. A fourth deploys. They operate independently, yet they collaborate as if they’ve worked together for years.

What makes this setup even more powerful is how cheap it is to scale. Using Claude Max or the Anthropic all-you-can-eat $20, $100, or $200 plans, I can run dozens of Claude-powered agents without worrying about token costs. It’s efficient, persistent, and cost-predictable. For what you'd pay a junior dev for a few hours, you can operate an entire autonomous engineering team all month long.

The real breakthrough came when I realized I could use claude-flow to build claude-flow. Recursive development in action. I created a smart orchestration layer with tasking, monitoring, memory, and coordination, all powered by the same agents it manages. It’s self-replicating, self-improving, and completely modular.

This is what agentic engineering should look like: autonomous, coordinated, persistent, and endlessly scalable.

See: https://github.com/ruvnet/claude-code-flow

🔥 One command to rule them all: npx claude-flow

Technical architecture at a glance

Claude-Flow is the ultimate multi-terminal orchestration platform that completely changes how you work with Claude Code. Imagine coordinating dozens of AI agents simultaneously, each working on different aspects of your project while sharing knowledge through an intelligent memory bank.

• Orchestrator: Assigns tasks, monitors agents, and maintains system state

• Memory Bank: CRDT-powered, Markdown-readable, SQLite-backed shared knowledge

• Terminal Manager: Manages shell sessions with pooling, recycling, and VSCode integration

• Task Scheduler: Prioritized queues with dependency tracking and automatic retry

• MCP Server: Stdio and HTTP support for seamless tool integration

All plug and play. All built with claude-flow.

🌟 Why Claude-Flow?

• 🚀 10x Faster Development: Parallel AI agent execution with intelligent task distribution

• 🧠 Persistent Memory: Agents learn and share knowledge across sessions

• 🔄 Zero Configuration: Works out-of-the-box with sensible defaults

• ⚡ VSCode Native: Seamless integration with your favorite IDE

• 🔒 Enterprise Ready: Production-grade security, monitoring, and scaling

• 🌐 MCP Compatible: Full Model Context Protocol support for tool integration

📦 Installation

# 🚀 Get started in 30 seconds
npx claude-flow init
npx claude-flow start

# 🤖 Spawn a research team
npx claude-flow agent spawn researcher --name "Senior Researcher"
npx claude-flow agent spawn analyst --name "Data Analyst"
npx claude-flow agent spawn implementer --name "Code Developer"

# 📋 Create and execute tasks
npx claude-flow task create research "Research AI optimization techniques"
npx claude-flow task list

# 📊 Monitor in real-time
npx claude-flow status
npx claude-flow monitor