Installation

Prerequisites

• Elixir >= 1.16
• Erlang/OTP >= 26
• SQLite3 (required by exqlite)
• An LLM API key (Anthropic, OpenAI, or both)
• br CLI (optional, for burst execution with beads)

Install

# Clone the repository
git clone https://github.com/chrisaddy/annihilation.git
cd annihilation

# Install dependencies
mix deps.get

# Compile the project
mix compile

# Set up API keys
export ANTHROPIC_API_KEY="sk-ant-..."
# and/or
export OPENAI_API_KEY="sk-..."

Dependencies

Phase 00 installs the following Mix dependencies (from mix.exs):

Dependency	Version	Purpose
exqlite	~> 0.23	SQLite3 persistence for beads database
jason	~> 1.4	JSON encoding/decoding
yaml_elixir	~> 2.11	YAML parsing
mint	~> 1.6	HTTP client for SSE streaming to LLM APIs
castore	~> 1.0	CA certificates for TLS
toml	~> 0.7	TOML parsing for config files
stream_data	~> 1.0	Property-based testing (dev/test only)
ex_doc	~> 0.34	Documentation generation (dev only)

Configuration

Configuration is loaded by Annihilation.Config from two locations, with project-local settings taking precedence:

Location	Purpose	Precedence
~/.annihilation/config.toml	Global user settings	Lower
$PROJECT_ROOT/.annihilation/config.toml	Project-local overrides	Higher

The config loader automatically detects the project root by walking up the directory tree looking for .annihilation/ or .git/ directories.

~/.annihilation/config.toml

[llm]
default_provider = "anthropic"
default_model = "claude-sonnet-4-20250514"

[tui]
fps = 30
theme = "dark"

[security]
shell_allowlist = ["git", "mix", "elixir", "cat", "ls", "grep"]

Initializing a project

Create the .annihilation/ directory in your project root:

mkdir -p .annihilation
# Optionally create a project-local config
touch .annihilation/config.toml

Install br (optional)

For burst execution with beads-based task management:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/beads_rust/main/install.sh" | bash
br init

Verify Installation

# Run the test suite
mix test

# Start the application (starts the OTP supervision tree)
iex -S mix

Once started, the supervision tree boots with 6 children:

1. Annihilation.Event.Registry — Registry-based PubSub
2. Annihilation.Beads.Keeper — SQLite database owner
3. Annihilation.Session.Store — JSONL session persistence
4. Annihilation.Agent.Supervisor — DynamicSupervisor for agents
5. Annihilation.Tether.QuestionQueue — Human-operator question queue
6. Annihilation.Burst.Manager — Burst/wave orchestration