Agent Swarms

​

Overview

​

What are Agent Swarms?

​

Use cases

• Research projects: One agent searches the web, another analyzes data, a third writes the report
• Code reviews: One agent checks style, another tests functionality, a third reviews security
• Content creation: One agent researches topics, another drafts content, a third edits and refines
• Data processing: Multiple agents process different data sources in parallel

​

How it works

@Andy research AI developments this week, analyze trends, and write a detailed report

1. Spawn a research agent to search and gather information
2. Spawn an analysis agent to identify patterns and trends
3. Spawn a writing agent to compile the final report
4. Coordinate between them and synthesize the results

​

Enabling Agent Swarms

// From src/container-runner.ts — session settings
env: {
  // Enable agent swarms (subagent orchestration)
  CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '1',
  // ... other settings
}

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
    "CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD": "1",
    "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "0"
  }
}

​

Agent team architecture

• Independent context and memory
• Access to the same mounted filesystems as the parent
• Ability to use all available tools (Bash, browser automation, etc.)
• Communication channel back to the main orchestrator agent

​

Session isolation

┌─────────────────────────────────────┐
│  Main Agent (orchestrator)          │
│  - Delegates tasks to sub-agents    │
│  - Coordinates results               │
│  - Responds to user                  │
└──────────┬──────────────────────────┘
           │
           ├─────────────┬─────────────┬──────────────
           │             │             │
    ┌──────▼──────┐ ┌───▼──────┐ ┌────▼─────────┐
    │ Sub-Agent 1 │ │Sub-Agent2│ │ Sub-Agent 3  │
    │ (Research)  │ │(Analysis)│ │  (Writing)   │
    └─────────────┘ └──────────┘ └──────────────┘

​

Example interactions

​

Research and analysis

@Andy analyze the top 10 posts on Hacker News today, categorize by topic, 
and identify emerging trends

• A web scraping agent to fetch HN posts
• Multiple analysis agents to categorize in parallel
• A synthesis agent to compile trends

​

Multi-source data aggregation

@Andy compile a weekly report from:
- Recent commits in the GitHub repo
- Updates in the Slack #engineering channel  
- Tickets closed in Linear

• A GitHub agent to analyze commit history
• A Slack agent to summarize channel activity
• A Linear agent to fetch closed tickets
• A reporting agent to compile everything

​

Parallel document processing

@Andy summarize all the PDFs in the research folder and create 
a comparison table

• Multiple document reading agents (one per PDF)
• A synthesis agent to create the comparison table

​

Memory and context sharing

• Group memory: The CLAUDE.md file in the group folder
• Mounted directories: Same filesystem access as the main agent
• Additional memory directories: Via CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD

// From src/container-runner.ts — session settings
env: {
  // Load CLAUDE.md from additional mounted directories
  CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD: '1',
}

• /workspace/group/CLAUDE.md (main group memory)
• /workspace/project/CLAUDE.md (for main channel only)
• /workspace/global/CLAUDE.md (read-only shared memory)

​

Coordination patterns

​

Sequential workflow

Main agent:
1. Spawn research agent → wait for results
2. Spawn analysis agent with research results → wait
3. Spawn writing agent with analysis → wait
4. Return final report to user

​

Parallel execution

Main agent:
1. Spawn 3 research agents in parallel
2. Wait for all to complete
3. Synthesize results
4. Return summary to user

​

Hierarchical delegation

Main agent:
1. Spawn coordinator agent for web research
   → Coordinator spawns multiple scraper agents
2. Spawn coordinator agent for data analysis  
   → Coordinator spawns multiple analysis agents
3. Synthesize both coordinators' results
4. Return to user

​

Performance considerations

​

Container limits

// From src/config.ts
export const MAX_CONCURRENT_CONTAINERS = Math.max(
  1,
  parseInt(process.env.MAX_CONCURRENT_CONTAINERS || '5', 10) || 5,
);

export MAX_CONCURRENT_CONTAINERS=10

​

Resource usage

• Runs in its own Claude Code session (API calls)
• May spawn its own container processes
• Shares CPU/memory with other containers

# Check running containers
docker ps | grep nanoclaw

# Monitor resource usage
docker stats

​

Debugging Agent Swarms

​

Check container logs

# View logs for a specific group
tail -f groups/{group-name}/logs/agent.log

​

Ask the agent

@Andy what sub-agents did you spawn for that task?
@Andy show me the breakdown of how you delegated the work

​

Check session files

ls -la data/sessions/{group-folder}/.claude/sessions/

​

Limitations

​

Best practices

​

When to use Agent Swarms

• Complex multi-step tasks with clear delegation opportunities
• Parallel data processing across multiple sources
• Tasks requiring different specialized skills
• Research projects with distinct gathering/analysis/writing phases

• Simple single-step queries
• Highly interactive conversations (stick to single agent)
• Time-sensitive requests (coordination adds latency)
• Tasks with strict resource constraints

​

Optimize swarm performance

1. Be explicit about delegation: Help the agent understand when to spawn sub-agents
   Copy

   Ask AI

   @Andy research X using multiple agents in parallel, then synthesize results
   
2. Provide clear sub-tasks: Break down your request to guide delegation
   Copy

   Ask AI

   @Andy:
   1. Fetch data from sources A, B, and C (parallel)
   2. Analyze each dataset
   3. Create comparison report
   
3. Monitor resource usage: Check if swarms are worth the overhead
   Copy

   Ask AI

   @Andy how many sub-agents did that task require?
   

​

Related documentation

• Scheduled tasks - Run agent swarms on a schedule
• Customization - Adjust container limits and behavior
• Web access - Sub-agents can use browser automation

​

External resources

• Claude Code Agent Teams documentation
• Agent orchestration patterns