anatomy of the swarm
Every agent is a real CLI process in its own tmux window, coordinated through a shared file-based mailbox. Orchestration is agent-agnostic — Claude Code by default, but the harness could just as well drive Codex CLI or Gemini CLI.
node · 01supervisor
Sits at the center of the colony. Decomposes goals into tasks, delegates to the right specialists, and integrates their results back into one coherent effort.
node · 02workers
Clone workers spin up in isolated git worktrees for conflict-free parallelism. Permanent workers persist across sessions, accumulating long-lived domain expertise.
node · 03reviewers
Independent auditors that read every change with fresh eyes — flagging design drift, risky diffs, and shortcuts before they merge into the trunk.
node · 04testers
Verification agents that run the suite, reproduce failures, and confirm claims. Nothing counts as done until a tester says it actually works.
substrate · 05mailbox + router
A shared file-based mailbox and a router daemon carry every message between agents — simple, inspectable coordination with no hidden channels.
substrate · 06health monitor
Watches every process. When an agent wedges or a change breaks the swarm, it auto-restarts and rolls back via git — the colony heals itself.
it remembers. it improves itself.
Most agent runs are amnesiac — everything learned evaporates when the process exits. soren keeps a persistent, private memory, and points its own swarm back at its own code.
it remembers
Memory persists across sessions, so day two starts smarter than day one.
- Daily journal — a running narrative of what the swarm did, decided, and learned.
- Hierarchical tasks — a SQLite-backed task tree tracks goals, subtasks, and status.
- Artifact storage — designs, reports, and outputs are preserved and referenced later.
it improves itself
The swarm's most interesting target is its own codebase.
- Self-directed work — agents file, prioritize, and implement improvements to soren itself.
- Reviewed & verified — self-modifications pass the same reviewer and tester gauntlet as any change.
- Safe by rollback — if an upgrade destabilizes the colony, the health monitor reverts it via git.
a public template, a private mind
soren ships as a public template: the code is public, and anyone can fork the colony. But your swarm's memories stay local and private — journals, tasks, and artifacts never leave your machine.
“The self is a relation which relates itself to its own self.”
Named for the philosopher of the self. A swarm that files tasks against its own codebase, reviews its own changes, and journals its own days is — in the only sense that matters here — a self relating itself to itself. Kierkegaard would have had notes.