shared-brain

Set up a shared context directory that enables coordination between the main agent and sub-agents. No frameworks, no complex messaging — just shared files.

Works with any AI coding agent that can read/write files.

The Pattern

shared-context/
├── priorities.md      ← Current focus (main agent updates)
├── agent-outputs/     ← Sub-agents drop completed work here
├── feedback/          ← User decisions that teach ALL agents
└── roundtable/        ← Cross-agent synthesis and insights

Why it works:

“Your agents don’t need to ‘talk’ to each other. They need to read from the same page.”

N agents with direct messaging = N² connections (complex, fragile) N agents with shared context = N connections (simple, robust)

Setup

1) Scan Workspace

Check what exists:

python3 skills/shared-brain/scripts/setup-shared-brain.py --workspace . --scan-only

2) Create Structure

Set up the shared-context directory:

python3 skills/shared-brain/scripts/setup-shared-brain.py --workspace .

This creates:

• shared-context/ directory with subdirectories
• shared-context/README.md explaining usage
• shared-context/priorities.md template
• Initial feedback log

3) Update Agent Instructions

Add shared brain instructions to your agent config. The script outputs a snippet:

python3 skills/shared-brain/scripts/setup-shared-brain.py --show-snippet

Usage

Main Agent (You)

Update priorities when user gives direction:

# shared-context/priorities.md

## Current Focus
1. [High priority task]
2. [Medium priority task]

## Queue
- [Upcoming work]

Log feedback when user approves/rejects work:

# shared-context/feedback/feedback-YYYY-MM-DD.md

### ✅ Approved
- [Decision]: [Lesson learned]

### ❌ Rejected  
- [Decision]: [Why, what to avoid]

Sub-Agents

When spawning sub-agents, include shared brain instructions:

FIRST: Read shared-context/priorities.md to understand current focus.

TASK: [Your task description]

OUTPUT: Write findings to shared-context/agent-outputs/{agent-name}-{date}-{task}.md

Reading Sub-Agent Output

After a sub-agent completes work:

cat shared-context/agent-outputs/*.md

Platform Examples

OpenClaw

sessions_spawn(task="""
  Read shared-context/priorities.md first.
  Do the research task.
  Write to shared-context/agent-outputs/research-{date}.md
""")

Claude Code

claude "Read shared-context/priorities.md, then do X, 
       write output to shared-context/agent-outputs/task.md"

Codex CLI

codex "Check shared-context/ for context, complete task, 
      save to agent-outputs/"

Scaling

3-5 Agents

Basic structure works as-is.

10+ Agents

Add subdirectories to agent-outputs:

shared-context/agent-outputs/
├── research/
├── content/
├── development/
└── analysis/

100+ Agents

Add:

• Read permissions (not every agent needs every file)
• Write queues (staging before merge)
• Git versioning for change tracking

Reference

See references/shared-brain-pattern.md for the full pattern explanation from @ericosiu’s viral thread.