Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/gabrielvuksani/wotann-code

the agentic coding harness
https://github.com/gabrielvuksani/wotann-code

agent-framework ai-agent anthropic claude computer-use free-tier harness llm mcp norse ollama openai provider-agnostic swift tauri typescript

Last synced: 3 days ago
JSON representation

the agentic coding harness

Awesome Lists containing this project

README 

          



# WOTANN



**The All-Father of AI agent harnesses.**



One install. Your providers. Every channel. Full autonomy.





  CI

  MIT License

  Node 22.13+

  Platforms

  25 providers

  25+ channels

  tests passing

  wotann.com

  AAIF aligned








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.










---



## 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.



|   | 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 |



---



## Quick Start



```bash

# 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

# 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.



```bash

# 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



```bash

# 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//` 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



| 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



```bash

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`](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 · 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



| Command | Purpose |

|---------|---------|

| `wotann init` | Initialize workspace |

| `wotann engine` | Start the KAIROS daemon |

| `wotann run ` | Non-interactive — execute a prompt with full harness intelligence |

| `wotann doctor` | Health diagnostics |

| `wotann arena` | Compare models blind side-by-side |

| `wotann autonomous ` | 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**: 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`.



```bash

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`](docs/AUTH.md).



---



## Documentation



| Doc | What's inside |

|---|---|

| [`WOTANN.md`](WOTANN.md) | Project codebook — architecture, conventions, naming, structure |

| [`identity.md`](identity.md) | Agent persona — voice, tone, character |

| [`soul.md`](soul.md) | Guiding principles — values, ethics, what the agent will/won't do |

| [`docs/AUTH.md`](docs/AUTH.md) | Daemon RPC authentication convention |

| [`docs/CAPABILITY_ADAPTATION_MATRIX.md`](docs/CAPABILITY_ADAPTATION_MATRIX.md) | How tool-calling / vision / thinking are synthesized on weaker models |

| [`docs/SKILLS.md`](docs/SKILLS.md) | Skill system — frontmatter spec, tool-flow rules, activation, install |

| [`docs/MCP.md`](docs/MCP.md) | MCP — install/import servers, run WOTANN as a server, scaffold one |

| [`docs/SEA_BUILD_ENVIRONMENTAL_GATE.md`](docs/SEA_BUILD_ENVIRONMENTAL_GATE.md) | Single-executable (SEA) build environment requirements |

| [`docs/SELF_HOSTED_RUNNER_SETUP.md`](docs/SELF_HOSTED_RUNNER_SETUP.md) | Self-hosted GitHub Actions runner for SEA + iOS jobs |

| [`CHANGELOG.md`](CHANGELOG.md) | Version history |

| [`AGENTS.md`](AGENTS.md) | AAIF AGENTS.md standard compliance file |



---



## Contributing



Pull requests welcome. See [`CONTRIBUTING.md`](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`](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](LICENSE) © 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