Agent Smith

Recursive Self-Similar Multi-Agent System —— Conflict-free Parallel Task Decomposition and Execution through Directory Isolation Protocol

English | 简体中文

---

Introduction

Agent Smith is a general-purpose multi-agent collaboration framework that enables multiple AI agents to work in parallel without conflicts through a strict directory isolation protocol.

Core Design Principles:

• Self-Similarity: Each agent (Smith) follows the same protocol and can recursively spawn child agents
• Conflict-Free Parallelism: Directory isolation ensures multiple agents can work simultaneously without interference
• Task Decomposition: Automatically breaks down complex tasks into parallelizable subtasks
• Platform Agnostic: Can run on any system or platform that supports multi-agent execution

---

Quick Start

Installation

Option 1: Claude Code Skill (Recommended)

Copy the agent-smith directory to Claude Code's skills directory:

# macOS / Linux
cp -r agent-smith ~/.claude/skills/

# Windows (PowerShell)
Copy-Item -Recurse agent-smith $env:USERPROFILE\.claude\skills\

Option 2: Standalone Usage

Copy the .agent-smith/ directory structure to your project:

cp -r .agent-smith-template ./my-project/.agent-smith

Usage

1. Initialize the Matrix

   Create the .agent-smith/ structure in your working directory:

   mkdir -p .agent-smith/smiths/smith-root/{inbox,private,outbox,children}
   mkdir -p .agent-smith/results

2. Define the Task

   Create a task file in the root agent's inbox/ directory:

   # task-001.md
   ## Task: AI Agent Market Research
   
   ### Objective
   Comprehensive understanding of AI Agent market landscape
   
   ### Subtasks
   1. Market trend analysis
   2. Key vendor research
   3. Technology development tracking
   4. Application scenario research

3. Start Execution

   The root agent reads the task and decides to execute directly or decompose and create child agents

---

Core Concepts

Smith (Agent)

A self-similar agent unit. Each Smith has:

• Unique ID (e.g., smith-root, smith-001)
• Level indicator (Level 0 is root, increments downward)
• Parent Smith reference (root has no parent)

Directory Isolation Protocol

.agent-smith/
├── smiths/
│   ├── smith-root/        # Root agent
│   │   ├── smith.md       # Agent definition (prompt)
│   │   ├── inbox/         # Task queue (parent writes, self reads)
│   │   ├── private/       # Private workspace
│   │   ├── outbox/        # Result output
│   │   └── children/      # Child agent directory
│   └── smith-001/         # Child agent
│       ├── smith.md
│       ├── inbox/         # Parent writes, self reads
│       ├── private/
│       ├── outbox/
│       └── children/
└── results/
    └── final.md           # Final result

Access Control Rules:

Directory	Permission	Description
inbox/	Parent write, self read	Task distribution queue
private/	Self-write only	Drafts, thoughts, temporary files
outbox/	Self-write only	Final result output
children/	Self-write only	Create child agents (parent privilege)

Execution Flow

Read task from inbox/
    ↓
Analyze task complexity
    ↓
┌─────────────┴─────────────┐
↓                           ↓
Can complete directly   Needs decomposition
    ↓                           ↓
Execute task          Design subtasks
    ↓                           ↓
Write to outbox/      Create child agents
                            ↓
                      Write tasks to child inbox/
                            ↓
                      Wait for child results
                            ↓
                      Aggregate results
                            ↓
                      Write to outbox/
                            ↓
                      End

---

Platform Integration

Claude Code

This repository includes a complete Claude Code Skill configuration:

• Skill Entry: agent-smith/SKILL.md
• Trigger Phrases: "create multi-agent system", "set up agent matrix", "decompose task for parallel execution"
• Auto-initialization: Automatically creates .agent-smith/ directory structure when triggered

Other Platforms

Agent Smith is an open protocol that can be implemented on:

• AutoGen - Using UserProxyAgent + AssistantAgent combination
• LangGraph - As a state machine workflow
• CrewAI - As Crew + Agents structure
• Custom Systems - Any environment supporting directory I/O and multi-processing

---

Example Scenarios

Market Research

Decompose complex AI Agent market research into 4 parallel subtasks:

1. Market trend analysis
2. Key vendor research
3. Technology development tracking
4. Application scenario research

→ View Full Example

Code Review

Break down large-scale code review into module-level parallel processing:

1. Data layer review
2. Business logic layer review
3. API interface layer review
4. Frontend component review

Content Creation

Distributed collaboration for content projects:

1. Outline design
2. Section writing (multiple authors in parallel)
3. Editing and proofreading
4. Format standardization

---

Best Practices

Task Decomposition Principles

1. Granularity Control: Each subtask should be completable in 1-4 hours
2. Independence First: Subtasks should have low coupling and minimal dependencies
3. Clear Interfaces: Each task should have well-defined input and output formats
4. Endgame Mindset: Avoid infinite decomposition; set maximum levels (recommend no more than 3)

Result Aggregation Tips

1. Cross-Validation: Check consistency between subtask results
2. Conflict Resolution: When conflicts are found, analyze causes and provide reasonable explanations
3. Incremental Aggregation: Partially aggregate results immediately after subtasks complete to avoid backlog
4. Traceability: Reference output paths of each subtask in aggregated results

---

Project Structure

agent-smith/
├── SKILL.md              # Claude Code Skill definition
├── smith.md              # Smith core prompt template
├── examples/             # Usage examples
│   ├── market-research.md
│   └── code-refactor.md
├── references/           # Reference materials
│   ├── concepts.md       # Core concept details
│   ├── protocol.md       # Protocol specification
│   └── best-practices.md # Best practices
└── templates/            # File templates

---

Protocol Specification

Hard Constraints

These limits are enforced by the Smith protocol. Changing them requires updating both SKILL.md and smith.md.

Constraint	Value
Maximum recursion depth	3 (Level 0 root → max Level 3)
Maximum children per Smith	5
Level ≥ 3 behavior	Must execute directly; decomposition forbidden

Agent Definition File (smith.md)

---
smith_id: smith-001
parent_id: smith-root
level: 1
created_at: 2026-03-05
---

# Smith {SMITH_ID}

## Identity
- ID: {SMITH_ID}
- Parent: {PARENT_ID}
- Level: {LEVEL}

## Task
Read inbox/task-{ID}.md and execute

## Constraints
- Only write to your own private/ and outbox/
- Can create child agents under children/
- Must output to outbox/result.md upon completion

Result Output Format (outbox/result.md)

# Result: {Task Title}

## Summary
One-sentence summary of the execution result.

## Detailed Results
...

## Subtask References (if any)
- smith-xxx: Responsible for ...
- smith-yyy: Responsible for ...

## Completion Status
- [x] Completed
- Completion time: 2026-03-05 12:00:00

Root Smith Responsibility

After writing its own outbox/result.md, the root Smith (Level 0) has an additional duty:

• Copy or summarize the root outbox/result.md to .agent-smith/results/final.md

This file serves as the single entry point for users to retrieve the complete output of the multi-agent session.

---

Contributing

Issues and Pull Requests are welcome.

Extension Ideas

• Visual monitoring dashboard
• Result version control
• Task priority queue
• Cross-matrix collaboration protocol

---

License

MIT © 2026 Chen Yijun