---

Why WOTANN

Most agent frameworks lock you to a vendor, degrade quietly when a model can't tool-call, and hand you a single UI. WOTANN inverts that. It lives at the layer above inference so your configured lab subscription or API-key provider remains replaceable without moving agent execution off your machine.

---

Quick Start

# Try without installing (any platform — needs Node 22.13+)
npx wotann@latest

# One-line install (macOS or Linux)
curl -fsSL https://raw.githubusercontent.com/gabrielvuksani/wotann/main/install.sh | bash

# Windows (PowerShell — see install.ps1)
irm https://wotann.com/install.ps1 | iex

# Or from npm (any platform)
npm install -g wotann

# Initialize a workspace
wotann init

# Start the always-on engine
wotann engine start

# Launch the TUI
wotann

Windows install

WOTANN runs on Windows 10/11 with Node.js 22.13+. The bash installer above is POSIX-only — Windows users have three supported paths:

# PowerShell one-liner (downloads and runs install.ps1)
irm https://raw.githubusercontent.com/gabrielvuksani/wotann/main/install.ps1 | iex

# Or from npm (when published) — works on every Node-supported OS
npm install -g wotann

# Or run without installing (npx pulls the latest published version)
npx wotann@latest

Node.js prerequisite on Windows: winget install OpenJS.NodeJS.LTS (Node 22.13+ required). The PowerShell installer enforces this; the npm path surfaces a friendly preflight error on older Node.

Agent execution and trust enforcement run on your machine. Inference uses a provider subscription or API key that you configure; WOTANN does not run local models or silently route prompts to anonymous public endpoints.

# Use frontier models when you want them
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=AIza...

# ChatGPT/Codex and Claude subscription paths are supported too
wotann onboard

There is no anonymous zero-config inference tier. If no authenticated remote processor is configured, WOTANN reports that honestly.

---

A Minute of WOTANN

# Fix failing tests autonomously — with a proof bundle
$ wotann autonomous "fix the failing tests in src/memory"
  [1/8] verification: 3 failing tests detected
  [2/8] strategy: minimal-change (preferred — tests are green-adjacent)
  [3/8] patch: memory/store.ts:441 null-check added, memory/hybrid.ts:88 guard
  [4/8] verification: tests + lint + typecheck all green · 46.01s
  [5/8] proof bundle: artifacts/proof-2026-04-20-133801.tar.gz
  [6/8] crystallize: skill saved as skills/fix-null-check-memory-store.md
  SUCCESS in 3 cycles · $0.42 · 47,000 tokens

# Compare three models blind, side-by-side
$ wotann arena "refactor this function for readability"
  ─── A ──────────  ─── B ──────────  ─── C ──────────
  [Opus output]     [GPT-5.4 output]  [Gemini 3 Pro output]
  Blind choice: B (revealed: GPT-5.4)

# Same conversation, phone tap
$ wotann link
  Scan QR on iPhone. Token transferred via ECDH. Session mirrored.

---

Headline Capabilities

Provider freedom (the moat)

Remote providers share one router with authenticated fallback chaining: preferred → other configured remote processors. Local runtimes and anonymous endpoints are excluded from executable fallback. If configured processors exhaust, WOTANN reports that honestly.

Runtime providers can be added without editing source: drop a strict provider.json under .wotann/providers/<name>/ with an OpenAI-compatible baseUrl, model list, capabilities, and an auth.envKey. WOTANN validates the manifest, refuses token-bearing manifests, and routes it through the same provider registry as built-ins.

Anthropic API    Anthropic Subscription   OpenAI    Codex (ChatGPT OAuth)
GitHub Copilot   OpenRouter               Gemini    HuggingFace
Azure            Bedrock                  Vertex    Mistral
DeepSeek         Perplexity               xAI       Together
Fireworks        SambaNova                Groq      Cerebras

The harness amplifies provider capabilities

capability-augmenter injects tool-calling, vision (via OCR + a11y tree), and extended thinking prompts into configured providers that lack native support. The trust layer stays independent of any one model family.

Multi-surface, one agent, one memory

Autonomous with proof, not vibes

wotann autonomous "fix the failing tests in src/memory"

Runs Ralph mode (verify-fix loop) + self-healing (provider fallback) + 8-strategy escalation (decompose, research-first, minimal-change, revert-and-retry, fresh-context, different-model, ask-for-help). Doom-loop detector prevents infinite cycles. Every completion ships a proof bundle: tests, typecheck, lint, diff summary, optional screenshots. Trust UI surfaces them to you.

Intelligence you can inspect

• Guardian post-response LLM-as-judge review (WOTANN_GUARDIAN=1)
• Self-consistency voting — N parallel samples with confidence score
• Council deliberation — 3-stage multi-provider peer review + chairman synthesis
• Unified knowledge fabric — single search API across memory / context-tree / graph-RAG / vector / FTS5, with deterministic retrieval fallbacks when no authenticated remote embedding processor is configured
• Context replay — priority-weighted reassembly under an explicit token budget
• Dream pipeline — nightly consolidation 02:00-04:00, extracts skills from successful runs

---

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│  Surfaces                                                           │
│  CLI · TUI · Desktop (Tauri) · iOS · Watch · CarPlay · 25 channels  │
└──────────────────┬───────────────────────────┬──────────────────────┘
                   │                           │
                   ▼                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│  KAIROS Daemon (always-on, ~/.wotann/kairos.sock)                   │
│  Session-token auth · 15s tick · cron · heartbeat · event triggers  │
└──────────────────┬───────────────────────────┬──────────────────────┘
                   │                           │
                   ▼                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│  WotannRuntime (composition root)                                   │
│  ┌─────────────┐ ┌─────────────┐ ┌────────────┐ ┌────────────────┐  │
│  │ 41-layer    │ │ 85 intel    │ │ 79 orch    │ │ 31-event hooks │  │
│  │ middleware  │ │ modules     │ │ modules    │ │ + DoomLoop     │  │
│  └─────────────┘ └─────────────┘ └────────────┘ └────────────────┘  │
│  ┌─────────────┐ ┌─────────────┐ ┌────────────┐ ┌────────────────┐  │
│  │ 8-layer     │ │ 4-layer     │ │ 25 prov    │ │ Skill registry │  │
│  │ memory      │ │ Computer Use│ │ + fallback │ │ + MCP registry │  │
│  └─────────────┘ └─────────────┘ └────────────┘ └────────────────┘  │
└──────────────────┬──────────────────────────────────────────────────┘
                   │
                   ▼
         Inference call (the only thing the LLM does)

See docs/CAPABILITY_ADAPTATION_MATRIX.md for how the harness equalizes capabilities across model tiers.

---

By the Numbers

---

Project Structure

src/
├── core/             Composition root (WotannRuntime) · agent bridge · types
├── providers/        25 entries in PROVIDER_DEFAULTS · router · rate limiter · format translator
├── middleware/       41-layer PIPELINE in `pipeline.ts` + TTSR streaming
├── intelligence/     85 modules that meaningfully affect model behavior
├── orchestration/    79 modules — coordinator · waves · PWR · Ralph · council · squads · canary · ...
├── memory/           80 modules · SQLite + FTS5 · 8 layers · vector · graph-RAG · episodic
├── context/          5 compaction strategies · legacy local-runtime code slated for subtraction
├── prompt/           Engine · 18 prompt modules · instruction provenance
├── hooks/            31 events (28 producer-wired · 3 advisory) · 23 guards · DoomLoop
├── computer-use/     4-layer perception + action stack (text-mediated for any model)
├── channels/         25+ adapters + DM pairing + node registry
├── voice/            Push-to-talk · authenticated remote STT/TTS adapters
├── learning/         autoDream · instincts · skill-forge · pattern-crystallizer
├── identity/         Persona system · soul/identity loading · Norse mythology
├── security/         Anti-distillation · PII redaction · sandbox · guardrails · SSRF guard
├── telemetry/        Cost tracker · session analytics · audit trail
├── marketplace/      MCP registry · skill marketplace · ACP agent discovery
├── ui/               Ink TUI · 20 themes · voice controller · diff engine · OSC 133 blocks
├── desktop/          Tauri config · companion server · app state
├── mobile/           iOS handlers · pairing · haptics · live activities
└── daemon/           KAIROS engine · IPC · RPC · cron · heartbeat

desktop-app/          Tauri 2 desktop (React + Rust) · ⌘K command palette
ios/                  SwiftUI app (5 targets — main · Intents · Widgets · Watch · Share)
docs/                 Architecture references (auth · surface parity · capability adaptation · build)
design-brief/         Design system: tokens · brand identity · surface guidelines · reference shots
skills/               138 SKILL.md entries (progressive disclosure; 18 BUILT_IN guards)

---

Commands

Run wotann --help for the full 78+ command surface.

---

Platforms

• macOS 13+ — full support including desktop DMG (ad-hoc signed)
• Linux — CLI + daemon (TUI optional)
• Windows 11 — CLI + daemon (Tauri build supported)
• iOS 18+ — companion app (TestFlight pending — clone + build in the meantime)
• watchOS 11+ — Watch companion (paired via iPhone)

---

Requirements

• Node ≥ 22.13 (current LTS; install via winget install OpenJS.NodeJS.LTS on Windows or brew install node@22 on macOS)
• macOS 13+ / Linux / Windows 11
• Optional: Python 3.11+ (for camoufox stealth browser backend), Xcode 16 (iOS builds)

---

Privacy

Agent execution and trust enforcement run locally. Inference payloads go only to the configured lab provider. Telemetry is opt-out and triple-gated — industry-standard DO_NOT_TRACK=1 is honored, plus WOTANN-specific WOTANN_NO_TELEMETRY=1, plus a sentinel file at ~/.wotann/no-telemetry.

export WOTANN_NO_TELEMETRY=1

No data leaves your machine unless you explicitly send it to a provider you chose. No phone-home. No analytics pings. No crash reporting without consent.

---

Configuration

Per-user config lives in ~/.wotann/:

~/.wotann/
├── wotann.yaml              # Providers · channels · MCP servers
├── session-token.json       # 256-bit daemon RPC auth token (chmod 0600)
├── memory.db                # SQLite + FTS5 — gitignored
├── sessions/                # Per-session JSON snapshots
├── dreams/                  # Dream-pipeline outputs
├── episodes/                # Episodic memory
├── logs/                    # Daily JSONL daemon logs
└── identity/                # SOUL.md · IDENTITY.md · AGENTS.md · etc.

---

Authentication

The daemon enforces session-token auth on every RPC call. Local clients (CLI, desktop, iOS) read ~/.wotann/session-token.json automatically. For development, set WOTANN_AUTH_BYPASS=1 — see docs/AUTH.md.

---

Documentation

---

Contributing

Pull requests welcome. See CONTRIBUTING.md for the development workflow, coding conventions (TypeScript strict, no any, immutable data, 200–400 LOC files), and how the planner → test-engineer → code-reviewer → verifier agent dispatch works.

The short version: fork, branch, TDD, open a PR. CI runs typecheck, lint, build, the full vitest suite, plus a dedicated iOS Simulator build job on every push.

---

Security

Found a vulnerability? See SECURITY.md for responsible disclosure. The daemon's RPC surface, the sandbox, and the Tauri configuration are the primary review targets.

---

Acknowledgements

WOTANN's harness ideas borrow generously from the open-source agent ecosystem. Notable inspirations: Hermes Agent (NousResearch), DeepAgents (LangChain), Open-SWE (LangChain), DeerFlow (ByteDance), oh-my-openagent, opcode, eigent, Aider, Cursor, Claude Code, Codex CLI, charmbracelet/crush, oraios/serena, can1357/oh-my-pi, Zed, Goose, and the Agent Communication Protocol (ACP) reference implementations.

---

License

MIT © 2026 Gabriel Vuksani