The All-Father of AI agent harnesses.
One install. Your providers. Every channel. Full autonomy.
|
WOTANN treats the LLM as just the inference call. Memory, tools, sandbox, orchestration, learning — all come from the harness. Inference comes from a remote subscription or API-key provider you configure. |
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.
| 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 normalizes provider capabilities |
| Inference economics | Resold tokens or bundled inference | BYO subscription or API key: the user pays the lab |
| 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 |
# 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
wotannWOTANN 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@latestNode.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 onboardThere is no anonymous zero-config inference tier. If no authenticated remote processor is configured, WOTANN reports that honestly.
# 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.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
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.
| 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 |
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.
- 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
┌─────────────────────────────────────────────────────────────────────┐
│ 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.
| 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 |
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)
| 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.
- 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)
- Node ≥ 22.13 (current LTS; install via
winget install OpenJS.NodeJS.LTSon Windows orbrew install node@22on macOS) - macOS 13+ / Linux / Windows 11
- Optional: Python 3.11+ (for camoufox stealth browser backend), Xcode 16 (iOS builds)
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=1No 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.
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.
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.
| 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 |
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.
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.
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.
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