@polderlabs/bizar

---

Table of Contents

• The Pantheon
• Architecture
• Installation
• Provider Setup
• Skill Discovery
• Routing
• Self-Improvement
• Contributing
• License

---

ᛉ The Pantheon

               ┌─────────────┐
               │ᛟ ODIN       │
               ├─────────────┤
               │Router (M3)  │
               └─────────────┘

 ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐
 │ᛢ VÖR    │ │ᛗ MIMIR  │ │ᚹ HEIMDALL│ │ᚱ HERMOD │ │ᚦ THOR   │ │ᛒ BALDR  │ │ᛏ TYR    │ │ᛉ VIDARR  │
 ├─────────┤ ├─────────┤ ├─────────┤ ├─────────┤ ├─────────┤ ├─────────┤ ├─────────┤ ├──────────┤
 │Clarify  │ │Research │ │Simple   │ │GitOps   │ │Medium   │ │Design   │ │Complex  │ │Last      │
 │DeepSeek │ │DeepSeek │ │DeepSeek │ │M2.7     │ │M2.7     │ │M2.7     │ │M3       │ │GPT-5.5   │
 │FREE     │ │FREE     │ │FREE     │ │$        │ │$        │ │$        │ │$       │ │$$       │
 └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └──────────┘

                                                                        ┌─────────────┐
                                                                        │ᚨ FORSETI    │
                                                                        ├─────────────┤
                                                                        │Auditor (M3) │
                                                                        │edit: deny   │
                                                                        └─────────────┘

Generated by PlantUML ASCII art (plantuml -utxt)

Agents

Agent	Rune	Model	Cost	Role
Odin	ᛟ	MiniMax M3	$0.30/M · $1.20/M out	Primary router — never executes, only delegates
Frigg	ᚠ	DeepSeek V4 Flash	Free	Read-only Q&A — ask questions, get answers, never modifies
Vör	ᛢ	DeepSeek V4 Flash	Free	Clarifies ambiguous requests — asks questions until task is well-defined
Mimir	ᛗ	DeepSeek V4 Flash	Free	Research & codebase exploration (Semble-first)
Heimdall	ᚹ	DeepSeek V4 Flash	Free	Simple tasks, quick edits, file operations
Hermod	ᚱ	MiniMax M2.7	$0.30/M · $1.20/M out	Git & GitHub operations (commit, PR, merge, rebase)
Thor	ᚦ	MiniMax M2.7	$0.30/M · $1.20/M out	Moderate implementation, debugging, refactoring
Baldr	ᛒ	MiniMax M2.7	$0.30/M · $1.20/M out	UI/UX design system (DESIGN.md plans, visual audits)
Tyr	ᛏ	MiniMax M3	$0.30/M · $1.20/M out	Complex implementation, architecture, deep debugging
Vidarr	ᛉ	GPT-5.5	Subscription	Last resort — GPT-5.5
Forseti	ᚨ	MiniMax M3	$0.30/M · $1.20/M out	Adversarial plan reviewer (edit: deny, audit-only)

---

Architecture

Request Flow

   User     Odin ᛟ          Subagent       Forseti ᚨ
    │         │                │              │
    │─Request─>│                │              │
    │         │                │              │
    │         │─ Decompose ────│              │
    │         │  into parallel │              │
    │         │  streams      │              │
    │         │                │              │
    │         │─ task ────────>│              │
    │         │─ task ────────>│              │
    │         │                │              │
    │         │     plan review (when complex)│
    │         │──────────────────────────────>│
    │         │    approve / changes required │
    │         │<──────────────────────────────│
    │         │                │              │
    │         │<─── results ───│              │
    │<─ synth ─│                │              │

Key behaviors:

• Odin never executes work — stripped of bash, glob, grep, edit, write, question
• Vör handles ambiguity — Odin cannot ask questions; routes unclear requests to Vör
• Always parallel — every request splits into 2+ simultaneous task calls
• Implementation splits across Thor + Tyr frontend/backend, file split, impl+tests
• Forseti gates all Tier 4/5 work — Tyr and Vidarr plans audited before execution
• Hindsight memory — per-project banks with bank_id: "<project-name>"; default bank for general knowledge only

---

Installation

Quick — npm (recommended)

Published on npmjs.com/package/bizar.

Run without installing:

npx bizar

Or install globally:

npm install -g @polderlabs/bizar
bizar

Or add to a project:

npm install @polderlabs/bizar
npx bizar

The interactive installer walks you through component selection, agent choice, install mode, API key setup, and auto-restarts opencode.

Windows users: the npm install -g @polderlabs/bizar command above is the recommended path on Windows. The installer uses irm | iex for uv, py -m pip for the pip fallback, taskkill for forced kills, and JS setTimeout instead of sleep — so it works on both Windows PowerShell and POSIX shells. See the Windows section below for prerequisites, known limitations, and the optional graph feature install.

Source — git clone (Linux/macOS contributors)

git clone git@github.com:DrB0rk/BizarHarness.git
cd BizarHarness
chmod +x install.sh
./install.sh

Copies agent definitions and config to ~/.config/opencode/, merges opencode.json, and prints next steps. Use this if you want to hack on BizarHarness itself.

This install.sh script is bash-only and does not run on Windows natively. Windows contributors should use the npm path above instead.

Windows

The bizar CLI is cross-platform — the npm install runs a Node.js installer that handles curl | sh redirects, signal handling, and temp paths on Windows PowerShell automatically.

Prerequisites

• Node.js 18+ on PATH
• Python 3.10+ (only required for the optional bizar graph knowledge-graph feature)
• Git for Windows — only needed if you want to run the bash install.sh from a Git Bash shell

Install

npm install -g @polderlabs/bizar
bizar

Optional: graph feature (knowledge graph + per-project .bizar/)

The bizar graph build subcommand uses graphify. Install uv and graphify from PowerShell:

# Install uv (Python package manager) — Windows-native PowerShell installer
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install graphify
uv tool install graphifyy

Then build the project graph from any repo:

bizar graph build

Known Windows limitations

• The blessed TUI library may render with quirks inside Windows Terminal; if you see garbled output in the TUI, use the browser UI via bizar dash start --bg and open http://localhost:4321 instead.
• Some shell scripts under config/skills/embedded-esp-idf/ are bash-only and require Git Bash (or WSL).
• The bash install.sh does not run on Windows cmd/PowerShell; use the npm install -g path above.
• RTK (Rust Token Killer) ships a bash-only installer. On Windows, install it manually via Cargo or a prebuilt binary, then run rtk init -g --opencode.

Prerequisites

• opencode CLI installed and on $PATH
• A Hindsight API key for persistent memory
• Provider connections (via /connect in opencode TUI)
• RTK (recommended) — CLI proxy that reduces LLM token consumption by 60-90%
• Semble (recommended) — AI-powered code search (used by Mimir agent)
• Skills CLI (recommended) — Agent skill package manager (npx skills add <owner/repo>)

RTK Setup

RTK (Rust Token Killer) filters and compresses command output before it reaches the LLM context. It saves ~80% on common operations like ls, git status, cargo test, and git diff.

Install:

# Homebrew (macOS)
brew install rtk

# Linux/macOS quick install
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

# Cargo
cargo install --git https://github.com/rtk-ai/rtk

Enable for opencode:

rtk init -g --opencode

After setup, all Bash commands are transparently rewritten to their rtk equivalents — git status → rtk git status, cargo test → rtk cargo test. The LLM receives compact output, saving 60-90% on token costs.

Semble Setup

Semble provides AI-powered code search. It indexes your codebase and enables natural-language queries like "where is authentication handled" without relying on grep. The Mimir research agent uses Semble as its primary search tool.

The BizarHarness installer handles this automatically. To install manually:

# Install uv if not present
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Semble with MCP support
uv tool install "semble[mcp]"

Skills CLI Setup

Skills CLI is a package manager for AI agent skills — like npm for agent capabilities. Install skills from any public GitHub repo with npx skills add <owner/repo>.

The BizarHarness installer handles this automatically. To install manually:

npm install -g skills

Then discover and install skills:

npx skills find              # Browse the skills directory
npx skills add <owner/repo>  # Install a skill from GitHub

Available for all major AI coding agents including OpenCode, Claude Code, Cursor, Copilot, Gemini, and more.

---

ᛉ Skill Discovery

BizarHarness agents proactively discover and install skills during execution using the Skills CLI. When Heimdall, Thor, Tyr, or Vidarr receives a task, they:

1. Assess whether a skill might exist for the task (framework-specific work, domain tasks, tool usage)
2. Check installed with skills list --json to see what's already available
3. Install from known repos based on the task domain — e.g., skills add supabase/agent-skills --all -y for database work, skills add vercel-labs/agent-skills --all -y for frontend
4. Use the skill's instructions at ~/.opencode/skills/<name>/SKILL.md via the skill tool

This happens automatically and on-demand — agents self-discover capabilities without manual configuration.

Known Skill Repositories by Domain

Domain	Repos
General (find-skills, skill-creator)	vercel-labs/skills
Frontend (React, a11y, web-design)	vercel-labs/agent-skills, shadcn/ui
Backend (Supabase, Postgres, auth)	supabase/agent-skills
Testing (TDD, E2E, Playwright)	mattpocock/skills, microsoft/playwright-cli
Design (frontend-design, UI/UX)	anthropics/skills, leonxlnx/taste-skill

---

---

Provider Setup

After installation, run /connect in opencode to add API keys:

Provider	Models	Auth
OpenCode Zen	opencode/deepseek-v4-flash-free	Free API key from opencode.ai — create account, get key, no charges
MiniMax (direct)	minimax/MiniMax-M2.7, minimax/MiniMax-M3	API key from MiniMax
OpenAI	openai/gpt-5.5	ChatGPT subscription (OAuth)

Then run /models to verify connectivity.

---

Routing

Task Type	Agent
Ambiguous or incomplete requests	@vör (free, asks clarifying questions)
File lookup, quick edits, boilerplate	@heimdall (free)
Codebase research, documentation analysis	@mimir (free, Semble-first)
Git commit, PR, merge, rebase, conflict resolution	@hermod (M2.7)
Moderate implementation, debugging, code review	@thor (M2.7)
Design systems, DESIGN.md, visual audits	@baldr (M2.7, plans only)
Complex features, architecture, deep debugging	@tyr (M3, audited by @forseti)
Stuck debugging, novel problems, postmortems	@vidarr (GPT-5.5, last resort)
Plan audit, adversarial review	@forseti (M3, edit: deny)

Cost escalation: Free → $Mid (M2.7) → $High (M3) → $$Ultra (GPT-5.5)

---

Self-Improvement

Every task records what was learned to .bizar/AGENTS_SELF_IMPROVEMENT.md at the project root. Odin reads it at session start and applies past patterns to current routing.

### 2026-06-16: Fixed routing issue
- **Context**: Odin was self-handling instead of routing
- **Lesson**: Stripped bash/glob/grep/edit from Odin — forces delegation
- **Pattern**: Primary agents should never have executable tools
- **Agent**: heimdall

---

Plans

BizarHarness includes a built-in visual plan editor for drafting architectural decisions, feature designs, and project plans. Plans are stored as MDX source files with an auto-generated HTML viewer/editor.

# Create a new plan
bizar plan new my-feature

# Open an existing plan
bizar plan open my-feature

# List all plans
bizar plan list

# Export plan to standalone file
bizar plan export my-feature > my-feature.mdx

# Delete a plan (with confirmation)
bizar plan delete my-feature

Plans are stored in plans/<slug>/ with four files:

File	Purpose	In git?
plan.mdx	Source content (the plan)	✓ Yes
plan.html	Viewer/editor (auto-generated)	✗ No
comments.json	Section comments	✗ No
meta.json	Title, status, author, timestamps	✓ Yes

The HTML viewer runs a tiny local HTTP server (localhost:4321) — no network, no sharing. Edit mode toggles all sections to textareas; comments appear in a side panel per section.

---

Contributing

PRs welcome. Please read CONTRIBUTING.md first.

---

Development

Development of BizarHarness uses a separate sandbox repo for Docker/dev tooling. See DrB0rk/BizarHarness-dev (private) for the local dev environment, including the Docker-based opencode sandbox used to test config and plugin changes without touching the system opencode install.

Note: When you push BizarHarness-dev to GitHub, update the URL above to match the actual repo location.

---

License

MIT — see LICENSE.

---