Introduction

Annihilation is an Elixir-based agent orchestrator where the user is the “Tether” — the thread back to base reality. Fire off tasks, psychonauts work autonomously in parallel, reach for the tether when uncertain, and everything is visible in a single TUI dashboard.

The BEAM’s actor model, supervision trees, and lightweight processes are a natural fit for multi-agent orchestration that no Python framework can match.

Design Principles

• Near-zero deps. Only exqlite (SQLite), jason (JSON), yaml_elixir (YAML), mint (HTTP/SSE), castore (TLS certs). Everything else built on OTP primitives.
• OTP-native. GenServer, DynamicSupervisor, Registry, ETS, Task.Supervisor — not third-party wrappers.
• First-principles TUI. Raw ANSI escape codes + Erlang raw mode. No TUI framework. Six modes: Overview, Focus, Tether, Grounding, Beads, Shell.
• No LLM framework. Hand-rolled HTTP calls to Anthropic APIs via Mint. Full control over streaming SSE parsing.
• Event system = Registry. Built-in Registry with :duplicate keys as the pub/sub backbone.
• Self-extending. Psychonauts define new psychonauts and tools at runtime. The system grows itself under Tether grounding.
• Memory-driven. Three-layer memory (episodic sessions, diary entries, playbook rules) with confidence scoring and anti-pattern detection. Thompson-sampled skill catalog.
• Reflection pipeline. Post-burst reflection extracts diary entries, proposes playbook deltas, validates evidence, and curates rules — all automatically.

Key Concepts

Concept	Description
Psychonaut	A GenServer running an LLM conversation loop with a phase machine: :idle -> :streaming -> :executing_tools -> :steering_check -> :done.
Provider	Behaviour abstracting LLM APIs. Anthropic provider ships built-in; Mock provider for testing. Providers normalize everything to canonical Message/Delta/ToolCall types.
Tool	A behaviour module that psychonauts invoke. 20+ built-in tools: shell, file ops, recursion, search, messaging, pipeline mutations, memory, skills.
Burst	A set of BeadRuns kicked off concurrently. Each BeadRun tracks a bead through its pipeline stages.
Wave	Repeated bursts until no ready beads remain. Closing beads in one burst can unblock beads for the next.
Pipeline	An ordered sequence of psychonaut stages (orchestrate -> code -> test -> review). Stages can be sequential or fan-out. YAML-seeded, runtime-mutable.
Tether	You. The human operator — the thread back to base reality — who dispatches tasks, answers reachings, reviews drifts, and grounds changes.
Drift	When a psychonaut proceeds without your answer. Recorded in the AssumptionsLedger. Groundable, rejectable, or superseded by late beacons.
Memory	Three layers: episodic (JSONL sessions + FTS5 search), working (diary entries), procedural (playbook rules with confidence decay).
Skills	Reusable prompt/code templates ranked by Thompson sampling. Adaptive exploration-exploitation via Beta distribution sampling.
Reflection	Post-burst pipeline: diary extraction -> playbook delta proposal -> evidence gate validation -> curator (dedup, conflict detection, anti-pattern inversion).

System Architecture at a Glance

Annihilation.Supervisor (:one_for_one)
|
+-- Event.Registry              # Registry (keys: :duplicate)
+-- Beads.Keeper                # SQLite persistence (WAL mode)
+-- Session.Store               # Append-only JSONL sessions
+-- Agent.Tool.Registry         # ETS-based tool registry
+-- Agent.Supervisor            # DynamicSupervisor
+-- Agent.DynamicSupervisor     # Named supervisor for agent spawn/monitor
+-- Agent.RecursionSemaphore    # Global concurrency limiter for recursive children
+-- Tether.QuestionQueue        # Priority-ordered human question queue
+-- Tether.AssumptionsLedger    # JSONL drift ledger with in-memory index
+-- Tether.LateBeaconHandler    # Late answer -> correction bead creation
+-- Burst.Manager               # Burst/wave lifecycle state machine

What Makes It Different

Unlike Python-based agent frameworks (LangChain, CrewAI, AutoGen), Annihilation:

• Uses the BEAM’s process model instead of threads/async
• Supervises psychonauts with OTP — crashes are recovered, not fatal
• Executes tool calls in true parallelism (not sequential)
• Hot-loads new psychonauts/tools without restarting
• Supports recursive sub-calls with depth limits, semaphores, and file lease inheritance
• Learns from past sessions via confidence-scored playbook rules and Thompson-sampled skills
• Runs a full reflection pipeline after every burst to extract knowledge
• Integrates with br (beads_rust) for issue tracking and task management