WOTANN

The All-Father of AI agent harnesses.

One install. Every model. Every channel. Full autonomy.

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 choice of model is always a drop-in. Switch from Claude → Gemini → Gemma mid-session and you keep the same memory, the same tools, the same capabilities.

| | Most agents | WOTANN | |---|---|---| | Provider | Locked to one vendor | 25 providers via openai-compat router; Anthropic + OpenAI subscriptions OR API keys | | Capabilities | Tool-calling, vision, thinking gated by model support | Capability augmentation injects all three for any model — even a 3B local Gemma | | Free tier | An afterthought | First-class: Ollama + Groq + Gemini 2.5 Flash free tier give the full experience | | Memory | Short-lived prompt context | 8-layer persistent: SQLite + FTS5 + vector + graph-RAG + episodic + temporal + provenance | | Surfaces | One UI | CLI + TUI + Desktop + iOS + Watch + CarPlay + 25 messaging channels | | Autonomy | Vibes | Proof bundles (tests + typecheck + diff + screenshots) on every completion | | Lock-in | Total | Zero — swap models mid-session, export all state |

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.

That's the whole setup. WOTANN runs entirely locally by default (Ollama + free tiers). Drop an API key to upgrade selectively — no lock-in, no telemetry unless you opt in.

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

# Or stay free
ollama pull qwen2.5-coder:7b
wotann                              # auto-detects Ollama

Zero-config public tier (no signup, no key)

If you have no API keys and no local Ollama, WOTANN still works out of the box. The runtime auto-falls through to an anonymous public-tier chain — no account, no credit card, no environment variable required.

# Cold-start with nothing configured. The TUI mounts and the first
# message routes through the public tier automatically.
npx wotann@latest

The chain is ordered by latency + rate-limit headroom (you can introspect with wotann providers list):

| Order | Provider | Model surface | Why | |---|---|---|---| | 1 | Pollinations.ai anonymous | openai-fast (GPT-OSS 20B reasoning, OVH backend) | Fast, ~1 req queued/IP | | 2 | LLM7.io anonymous | GLM-4.6V (vision) + Codestral (code) | 30 RPM, vision-capable | | 3 | OVHcloud anonymous | Llama 3.3 70B, GPT-OSS 120B, Qwen2.5-VL 72B | 2 RPM/IP, vision-capable | | 4 | AI Horde | Community-pooled models | Uncensored fallback; queue-dependent |

Rate-limit errors fall through to the next adapter without surfacing to the user. When all four are saturated WOTANN reports honestly — no silent retries, no fake success. Disable the public tier entirely with WOTANN_DISABLE_PUBLIC=1 for sandboxed/offline runs.

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)

25 providers via one router with automatic fallback chaining: preferred → other paid → Gemini → Ollama → free. The model is never silently degraded — if your chosen Opus is rate-limited, WOTANN tries Opus via another provider first; only when all paid paths exhaust does it fall back to Gemini/local.

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   Ollama                   Gemini    HuggingFace
Azure            Bedrock                  Vertex    Mistral
DeepSeek         Perplexity               xAI       Together
Fireworks        SambaNova                Groq      Cerebras

The harness amplifies — even on a 3B local model

capability-augmenter injects tool-calling, vision (via OCR + a11y tree), and extended thinking ("step by step" prompts) into providers that lack native support. Combined with hash-anchored editing, line-bucketed loop detection, and 41 forced-verification middleware layers in the PIPELINE, a Qwen2.5-Coder:7B running locally gets the same forced verification, frustration detection, doom-loop guards, and memory system as Claude Opus.

Multi-surface, one agent, one memory

| Surface | What you get | |---|---| | CLI | 78+ commands incl. init, engine, autonomous, arena, link, enhance, cost | | TUI | Ink-rendered REPL · Obsidian Precision theme · voice push-to-talk · slash commands · OSC 133 blocks | | Desktop (Tauri 2) | Chat / Editor (Monaco) / Workshop / Exploit / Trust / Integrations · Command palette ⌘K · Computer Use panel | | iOS (SwiftUI) | Phase C chat · Phase D work tab with filter pills · Phase E onboarding wizard | | Apple Watch | Quick actions (run tests, build, lint, approve, voice) via WCSession | | CarPlay | Hands-free dispatch with list + detail templates | | Widgets + Live Activities | Cost + agent status widgets · Dynamic Island progress | | Share Extension | Send any text/URL into a WOTANN conversation from any iOS app | | Siri Intents | AskWOTANN · CheckCost · EnhancePrompt | | Channels (25+) | Telegram · Slack · Discord · Signal · WhatsApp · iMessage · Teams · Matrix · Mastodon · WeChat · LINE · Viber · DingTalk · Feishu · Email · SMS · Webhooks · GitHub bot · IDE bridge · IRC · Google Chat · webchat · + more |

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 wotann memory embeddings warmup for local BGE embeddings that keep semantic memory usable offline after the model is cached
• 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

| | | |---|---| | Source | 2,551 TypeScript files in the current tree (1,380 src · 1,171 tests) | | Middleware | 41 PIPELINE layers (in src/middleware/pipeline.ts) | | Providers | 25 entries in PROVIDER_DEFAULTS (7 distinct adapter backends + capability augmentation) | | Channels | 41 modules in src/channels/ | | Surfaces | 7 (CLI · TUI · Desktop · iOS · Watch · CarPlay · Channels) | | Memory layers | 8 (FTS5 · vector · graph-RAG · episodic · semantic · temporal · working · archival) | | Intelligence modules | 85 in src/intelligence/ (auto-reviewer · verification-cascade · DAP · karpathy-principles · …) | | Orchestration patterns | 79 modules in src/orchestration/ (coordinator · waves · PWR · Ralph · council · squads · canary · …) | | Skills | 138 SKILL.md entries under skills/ + 18 BUILT_IN code-embedded guards | | Hook events | 31 (28 producer-wired · 3 advisory) with 23 BUILT_IN guards |

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 · Ollama KV cache compression
├── 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 · STT/TTS · WhisperKit · Edge TTS · faster-whisper
├── 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

| Command | Purpose | |---------|---------| | wotann init | Initialize workspace | | wotann engine | Start the KAIROS daemon | | wotann run <prompt> | Non-interactive — execute a prompt with full harness intelligence | | wotann doctor | Health diagnostics | | wotann arena | Compare models blind side-by-side | | wotann autonomous <task> | Autonomous execution with proof bundle | | wotann link | Pair an iPhone via PIN or Bonjour | | wotann onboard | Interactive provider setup | | wotann voice | Push-to-talk voice mode | | wotann loop "prompt" --interval 5m | Self-pacing recurring prompt | | wotann channels | Manage messaging channel adapters | | wotann cost | Predict or review session cost |

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: Ollama (local models), Python 3.11+ (for camoufox stealth browser backend), Xcode 16 (iOS builds)

Privacy

Runs entirely locally by default. 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

| Doc | What's inside | |---|---| | WOTANN.md | Project codebook — architecture, conventions, naming, structure | | identity.md | Agent persona — voice, tone, character | | soul.md | Guiding principles — values, ethics, what the agent will/won't do | | docs/AUTH.md | Daemon RPC authentication convention | | docs/CAPABILITY_ADAPTATION_MATRIX.md | How tool-calling / vision / thinking are synthesized on weaker models | | docs/SKILLS.md | Skill system — frontmatter spec, tool-flow rules, activation, install | | docs/MCP.md | MCP — install/import servers, run WOTANN as a server, scaffold one | | docs/SEA_BUILD_ENVIRONMENTAL_GATE.md | Single-executable (SEA) build environment requirements | | docs/SELF_HOSTED_RUNNER_SETUP.md | Self-hosted GitHub Actions runner for SEA + iOS jobs | | CHANGELOG.md | Version history | | AGENTS.md | AAIF AGENTS.md standard compliance file |

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

"Think like Odin: see the whole board, pay the price for true knowledge, speak directly, build what will last, and let Huginn and Muninn carry the memory forward."

— .wotann/SOUL.md

Built with TypeScript · SwiftUI · Rust · Ink · Tauri 2 · Vite