By Nat Weerawan + Neo Oracle (Claude Opus 4.6) — April 2026
This document describes an architecture born from a real problem: what happens when you give AI agents access to 30+ repositories and ask them to manage everything? They drown. Not in computation, but in context.
The Shadow Oracle Architecture is our answer. It emerged from building maw-js — a multi-agent orchestration system running 14+ AI agents across dozens of projects — and hitting the wall where more capability created less coherence.
The core insight: AI agents should think about projects the way humans do. One domain at a time. Deeply. With parallel hands when needed, but one brain per project.
In early 2026, we had an oracle named Pulse. It was supposed to be the project manager — tracking tasks, calculating timelines, aggregating reports across all our projects: flood monitoring (Floodboy), fire detection (Fireman), air quality sensing (DustBoy), crypto exchange integration (Bitkub), AI workshops (Arthur), and more.
Pulse had 17 worktrees. Each worktree pointed to a different repository. Each repository was a different domain. Pulse was supposed to understand all of them.
It couldn't.
Not because the AI wasn't capable — Claude can reason about anything you put in its context window. The problem was cognitive architecture. Pulse's memory (its ψ/ directory) was a flat collection of learnings from wildly different domains:
ψ/memory/learnings/
├── bitkub-api-rate-limits.md
├── pm25-sensor-calibration.md
├── fire-hotspot-satellite-imagery.md
├── mdc-workshop-curriculum.md
├── flood-water-level-thresholds.md
└── quarterly-tax-calculation.md
When Pulse tried to work on tax calculation, it had to wade through sensor calibration notes. When it tried to plan a workshop, fire detection learnings were noise. Every task carried the weight of every other task's context.
This is exactly how a human burns out: not from hard work, but from too many unrelated responsibilities without boundaries.
Git worktrees are brilliant for parallel development. You can work on two features simultaneously in the same repository — separate working directories, shared history, isolated branches.
But we were using worktrees for something they weren't designed for: cross-project management. Neo (our code oracle) had worktrees pointing to 8 different repositories. That's not parallel development — that's an oracle pretending to be eight different people.
The confusion was subtle because worktrees WORKED mechanically. git worktree add doesn't care if the task is related to the parent repo. Tmux windows spawn regardless. Claude Code runs in any directory. Everything functioned. Nothing cohered.
An oracle should own one domain. Like a human specialist:
- Floodboy thinks about floods. Water levels, rain gauges, government contracts for monitoring stations.
- Fireman thinks about fires. Satellite imagery, hotspot detection, smoke sensors.
- Pulse thinks about project management. Timelines, task allocation, reporting, tax.
Each oracle has its own repository, its own ψ/ memory, its own CLAUDE.md identity. When Floodboy learns something about sensor deployment, that learning stays in Floodboy's brain. It doesn't pollute Fireman's context.
floodboy-oracle/
├── src/ # Floodboy's code
├── CLAUDE.md # Floodboy's identity
└── ψ/
└── memory/
└── learnings/ # Only flood-related knowledge
Within a single project, an oracle may need to do multiple things at once. A developer might be fixing a bug on one branch while implementing a feature on another. This is what worktrees (shadows) are for:
floodboy-oracle/ # Main repo
floodboy-oracle.wt-1-sensor-api/ # Shadow: building sensor API
floodboy-oracle.wt-2-dashboard/ # Shadow: building dashboard
Each shadow is a git worktree — same repository, different branch, separate working directory. Each gets its own tmux window and Claude Code session. They share git history but work independently.
The key constraint: shadows must belong to the same project. A Floodboy shadow that points to the Fireman codebase is an architectural violation. If Floodboy needs to contribute to Fireman, that contribution flows through Fireman's own oracle.
Some concerns span multiple projects. Tax calculation needs financial data from ALL children. Quarterly reporting aggregates metrics across the fleet. Client billing crosses project boundaries.
This is where the parent oracle lives:
pulse (parent/aggregator)
│ Owns: cross-project concerns (tax, reporting, planning)
│ Brain: aggregated knowledge from all children
│
├── floodboy (child)
│ Owns: flood monitoring
│ Shadows: sensor-api, dashboard (parallel tasks)
│
├── fireman (child)
│ Owns: fire detection
│ Shadows: satellite-feed, alert-system
│
├── dustboychain (child)
│ Owns: air quality
│
└── arthur (child)
Owns: AI workshops
The parent doesn't DO the work on each project. It doesn't write flood monitoring code or fire detection algorithms. It AGGREGATES — pulling knowledge from children to serve cross-cutting concerns.
Knowledge flows upward through soul sync. When a child oracle completes a task:
1. maw done (task complete)
└── commit + push (save code)
└── reunion (worktree ψ/ → main repo ψ/)
└── soul-sync (child ψ/ → parent ψ/)
Three levels of knowledge consolidation:
| Level | Mechanism | Scope |
|---|---|---|
| Reunion | maw reunion |
Shadow → Main repo (same git) |
| Soul Sync | maw soul-sync |
Child → Parent (different repos) |
| Oracle MCP | oracle_search |
Any oracle → shared DB (cross-fleet) |
Each level has different tradeoffs:
- Reunion is instant (file copy within same git worktree structure)
- Soul sync is deliberate (cross-repo copy, triggered manually or on done)
- Oracle MCP is always-available (server-based, semantic search, real-time)
The word "shadow" carries meaning beyond git mechanics. A shadow is a parallel context — a version of reality where the oracle can explore without disturbing the main timeline.
In our implementation, shadows are git worktrees. But conceptually, a shadow could be:
- A worktree — same repo, different branch, parallel development
- A knowledge overlay — a ψ/ directory attached to ANY repository, even one you don't own
- A speculative branch — an exploration that may or may not merge back
The third type is the most interesting. When an oracle creates a shadow to explore an idea, the shadow's ψ/ captures learnings from the exploration. Even if the code is never merged, the knowledge persists. The shadow "dies" but its memories live on through reunion.
The deepest insight: ψ/ replaces external tools as the interface between AI and context.
Traditional approach:
AI agent → query MCP server → get context → work → report back
Shadow approach:
AI agent → reads ψ/ in its own repo → has context → works → writes to ψ/
The second approach is:
- Self-contained:
git clonegives you the full brain. No external dependencies. - Portable: works offline, works on any machine, works in CI/CD.
- Git-native: knowledge is versioned, diffable, reviewable in PRs.
- Human-readable: markdown files, not database entries.
The MCP server becomes an INDEX of ψ/ directories across the fleet, not the source of truth. The truth lives in the repos.
The current implementation of soul sync copies files from child to parent:
child ψ/memory/learnings/sensor-drift.md → parent ψ/memory/learnings/sensor-drift.md
This is necessary but not sufficient. A parent with 10 children, each generating 50+ learnings, accumulates 500+ raw files. The parent's ψ/ becomes a landfill.
The future of soul sync isn't file copy — it's knowledge transformation:
child generates: "PM2.5 sensor at station 7 shows 15% drift after 6 months at 40°C"
parent receives: "DustBoy Q1: sensor maintenance needed at 3 stations, est. cost 45K THB"
The child's raw learning is domain-specific and detailed. The parent needs a summary relevant to its concerns (budget, timeline, risk). An AI step in the sync pipeline transforms the knowledge:
child ψ/file → AI distill (for parent's context) → parent ψ/summary
This isn't implemented yet. But the architecture supports it: soul-sync already knows the parent-child relationship, knows which files are new, and has access to both oracle's CLAUDE.md (identity/context). The distillation step slots naturally into the pipeline.
Not everything needs transformation:
| Content | Treatment |
|---|---|
| Financial data (invoices, costs) | Copy as-is (parent needs exact numbers) |
| Technical learnings | Distill (parent needs impact, not implementation) |
| Retrospectives | Summarize (parent needs patterns, not session details) |
| Traces | Copy as-is (searchable index) |
The rules would live in the parent's configuration — "from Floodboy, I need financial data verbatim and technical learnings summarized."
The current architecture flows upward: child → parent. But real organizations communicate in all directions:
Downward (parent → children):
- "Tax deadline March 31 — all children report expenses by March 25"
- "New compliance requirement: all sensor data must be encrypted at rest"
- "Budget freeze: no new hardware purchases until Q2"
Lateral (sibling → sibling):
- Floodboy shares a rain gauge calibration technique with Fireman (both use weather sensors)
- DustBoy shares a government reporting template with Floodboy (both are government contracts)
Downward flow: parent writes to ψ/outbox/broadcast/ → soul-sync PUSHES to all children's ψ/inbox/.
Lateral flow: oracle A writes to ψ/outbox/to-fireman/ → soul-sync routes to Fireman's ψ/inbox/from-floodboy/.
Both build on existing primitives:
ψ/inbox/already exists (maw uses it for inter-oracle messaging)ψ/outbox/already exists (ideas, handoffs)- Soul sync already knows the family tree (parent/children)
The routing is just another sync direction.
Look at the orange box in the center of the diagram. It's labeled "Repo Oracle." It connects to every project repo. It IS the oracle.
This repo might contain:
pulse-oracle/
├── CLAUDE.md # Identity: "I am the aggregator"
├── ψ/
│ ├── memory/
│ │ ├── learnings/ # Aggregated from all children
│ │ ├── retrospectives/ # Cross-project patterns
│ │ └── traces/ # Fleet-wide search logs
│ ├── inbox/ # Messages from children
│ └── outbox/ # Broadcasts to children
├── dashboards/ # Cross-project reporting
└── tax/ # Financial aggregation
No src/ with application code. No package.json for a runtime. This is a pure knowledge repository. Its "code" is its organizational intelligence — the dashboards, reports, and aggregation logic that make sense of children's contributions.
This is radical: an AI agent whose entire purpose is to think, not to code. It reads, synthesizes, reports, and plans. The children do the building.
Zoom out one more level. The Repo Oracle aggregates from project repos. But who aggregates from Repo Oracles?
The human. Nat.
project repos → child oracles → parent oracle → human
code specialists aggregator decision-maker
Each layer reduces complexity. 30 repos become 10 child oracles become 2-3 parent oracles become 1 dashboard that a human can actually comprehend.
This is the real architecture: a hierarchy of AI minds that compresses complexity at each level, until a human can hold it in their head.
Fleet config (~/.config/maw/fleet/):
// 01-pulse.json (parent)
{
"name": "01-pulse",
"children": ["floodboy", "fireman", "dustboychain", "arthur"],
"windows": [
{ "name": "pulse-oracle", "repo": "laris-co/pulse-oracle" }
]
}
// 06-floodboy.json (child)
{
"name": "06-floodboy",
"parent": "pulse",
"windows": [
{ "name": "floodboy-oracle", "repo": "laris-co/floodboy-oracle" }
]
}# Parent pulls from all children
maw soul-sync pulse
# Child pushes to parent (auto-detect)
maw soul-sync
# Short alias
maw ss pulse
# Create a shadow (worktree) for parallel work
maw wake floodboy sensor-api
# Complete work: commit → reunion → soul-sync → cleanup
maw done floodboy-sensor-apiDeveloper works in shadow (worktree)
→ learns something, writes to ψ/memory/learnings/
→ maw done
→ git commit + push (save code)
→ maw reunion (shadow ψ/ → main repo ψ/)
→ maw soul-sync (child ψ/ → parent ψ/)
→ parent now has the knowledge
→ parent can aggregate, report, plan
- Auto soul-sync on
maw done(Phase 4) - Edge case hardening (Phase 5)
- Bidirectional sync (parent → children broadcasts)
- AI-powered distillation in the sync pipeline
- Lateral sibling sync
- Federation: soul-sync across machines (white ↔ mba)
- Self-organizing oracle families (children propose their own parent)
- Knowledge decay (old learnings fade, recent ones are weighted)
- Cross-organization soul sync (your oracle fleet talks to my oracle fleet)
The Shadow Oracle Architecture isn't about technology. It's about how intelligence should be organized.
One mind per domain. Shadows for parallel exploration. Knowledge flows upward through soul sync. Parents aggregate but don't micromanage. The human sees the big picture.
This mirrors how the best human organizations work: specialists who go deep, managers who synthesize, executives who decide. The difference is that our specialists never sleep, never forget, and can be spun up or down in seconds.
The pulse never stops. The shadows keep working. The oracle sees all.
"Each agent should think about a project like a human — that's easier." — Nat Weerawan, April 2026
| Version | Date | What |
|---|---|---|
| 1.5.2 | 2026-04-06 | Stop swallowing tmux stderr |
| 1.5.3 | 2026-04-06 | Fix new-window collision on base-index ≠ 0 |
| 1.5.4 | 2026-04-06 | Skip worktree loop when task specified; remove maw-fleet.service |
| 1.6.0 | 2026-04-06 | maw soul-sync — parent-child oracle ψ/memory sync |
| Project | Role |
|---|---|
| maw-js | Multi-agent orchestration (this project) |
| arra-oracle-v3 | Oracle MCP server (knowledge DB) |
| pulse-cli | Project management CLI |
| proof-maw-multi-agent-worktree-kit | Proof of concept |