🧙‍♂️ Wizard-AI

It says nothing. It catches the crash. It cuts 78% tokens. It works.

~78% fewer tokens (up to 94%) · ~80% cheaper · 5x faster · 100% safe & rollback-protected

Measured on real coding agent sessions across complex architectures, bug diagnoses, and framework installations. Wizard-AI orchestrates #ponytail (lazy senior dev discipline), #caveman (-75% CLI tokens), #sqz (20x JSON compression), and wizard-ai os (automatic zero-downtime rollback gates). Every safety check is active while your context stays razor-sharp.

🧭 Modular Documentation & Guides

Instead of a monolithic manual, Wizard-AI is organized into hyperlinked modular guides:

🔥 The Hard Technical Problem: The $50/Feature Hallucination & Environment Brick Tax

When you let a modern AI coding agent (like raw Claude Code, OpenHands, Aider, or Cursor) run loose on a real-world repository, you immediately hit two systemic, multi-million dollar engineering bottlenecks:

1. The Context-Window Avalanche & Financial Burn: Raw agents dump 80,000+ tokens of entire file trees, verbose test logs, and npm install outputs into their context window on every turn. They quickly exhaust API limits, suffer from severe context degradation (hallucinations), and cost ~$18.50 per feature while writing bloated, unmaintainable code.
2. The Silent Environment Corruption (The "2 AM Brick"): When an agent runs npm install -g, uv tool install, or bun add during an autonomous loop, a broken package, incompatible C++ build dependency, or syntax error can completely corrupt your global system runtime. Standard agents don't know how to clean up their mess, leaving you with broken virtual environments and half-created directories.

💡 How Wizard-AI Solves It Permanently

Wizard-AI acts as a Self-Healing Abstraction Layer (wizard-ai os) & Deterministic 5-Loop Orchestrator between your AI agent and your OS:

flowchart TB
    %% Nodes
    User([👤 User Request]) --> Router{🧙‍♂️ auto-router}
    
    %% Engine Loops
    subgraph Engine [⚙️ ENGINE-LOOPS: Sequential Execution]
        Router --> L1[01. loop-1-plan]
        L1 --> L2[02. loop-2-develop]
        L2 --> L3[03. loop-3-debug]
        L3 --> L4[04. loop-4-refactor]
        L4 --> L5[05. loop-5-release]
    end
    
    %% Reference Library
    subgraph Lib [📚 REFERENCE LIBRARY: On-Demand Context]
        Ref[skills/reference/]
        Ref --> RefCore[core]
        Ref --> RefFE[frontend]
        Ref --> RefBE[backend]
        Ref --> RefDO[devops]
        Ref --> RefMisc[misc / stitch / data-science]
    end
    
    %% Connections
    L1 -.->|Consents Specs| Ref
    L2 -.->|TDD & Dev| Environment[💻 User Environment]
    L3 -.->|Auto-Debug| Environment
    L5 -.->|Auto-Release| GitHub[🐙 GitHub Repo / NPM]
    
    %% Styling
    classDef engineColor fill:#6366f1,stroke:#4f46e5,stroke-width:2px,color:#fff;
    classDef libColor fill:#10b981,stroke:#059669,stroke-width:2px,color:#fff;
    classDef mainColor fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#fff;
    class L1,L2,L3,L4,L5 engineColor;
    class Ref,RefCore,RefFE,RefBE,RefDO,RefMisc libColor;
    class Router mainColor;

📊 Concrete Token ROI & Financial Benchmarks

Wizard-AI combines all major token-compression and behavioral discipline engines into a single unified pipeline:

🧠 Agentic Context Engineering & The 4-Layer Format Stack

1. Layer 4: JavaScript (Execution) — Workflow logic runs in secure sandboxes via pi-extensible-workflows.
2. Layer 3: YAML (Orchestration) — Purely for routing, configuration, and agent roles.
3. Layer 2: Markdown + LEA (Content) — Uses Lossless Evidence Aliases (LEA) to save 60-80% on repetitive semantic memory.
4. Layer 1: TOON Format (API Boundaries) — Replaces bloated JSON with Token Oriented Object Notation (TOON) via @toon-format/toon (40-75% token reduction).

⚡ Quick Start & Installation

1. Full Platform Guided Setup (Recommended)

This is the interactive guided configuration wizard for first-time users. It configures WIZARD_AI_DIR, .bashrc aliases, and ensures all dependencies are present.

On Linux / macOS:

./setup.sh
# Alternatively via npx:
npx --no-cache -y @darkrei08/wizard-ai-cli@latest setup --verbose

On Windows (PowerShell):

.\setup.ps1

2. Interactive Terminal Engine (Skills & Frameworks Manager)

If you already ran the guided setup and just want to launch the Skill Manager directly. To see verbose logs printed to the video during skill installations, append the --verbose flag:

npx --no-cache -y @darkrei08/wizard-ai-cli@latest --verbose

3. Run via Docker (Isolated Web GUI)

If you prefer to keep the web environment containerized:

docker compose up -d

The interface will be available at http://localhost:9742.

📦 Packages in this Monorepo

Package	Type	Description	Link
@darkrei08/wizard-ai-cli	Core CLI Engine	Master installer, skill synchronizer, and workflow dispatcher
@darkrei08/pi-cockpit-tools	Pi Extension	Native Pi extension for Cockpit Tools multi-account rotation & slash commands	pi-cockpit-tools
pi-cockpit-proxy-setup	CLI Installer	Interactive model selector & rotator proxy installer script

🛠️ Cockpit Tools & Proxy Rotator Quick Commands

# Menu Interattivo (Account + Modelli LLM):
wz-ai cockpit

# Cambio Account Diretto:
wz-ai cockpit switch <email|numero>

# Cambio Modello Predefinito:
wz-ai cockpit model <nome-modello>

# Auto-Rotazione Account su Quota Più Alta:
wz-ai cockpit auto-rotate

# Stato Quote e Account:
wz-ai cockpit status

⚙️ What gets installed?

Behind the scenes, setup.sh handles everything for you:

1. Registers $WIZARD_AI_DIR: Saves the repo path in ~/.config/wizard-ai/env and appends a load instruction to your shell (~/.bashrc, ~/.zshrc).
2. Prepares python-venv: Installs the uv package manager and creates a lightweight virtual environment (~/.wizard-ai/venv).
3. Clones dependency repos: Downloads required helper repositories under .local-clones/.
4. Installs Global CLI Tools: Installs compiled tools (graphify, litellm, markitdown, sqz, serena) globally via uv tool.
5. Deploys Custom Wrappers: Copies the scripts from bin/ to ~/.local/bin/.
6. Configures Agent Skills: Deploys all agent skills to ~/.gemini/config/skills/ and runs wizard-ai sync-skills to copy them to other agent folders.

🔄 5 Sequenced Loop-Engineering Workflows (01 → 05)

Wizard-AI organizes all development, debugging, refactoring, and release tasks into 5 Sequenced Numbered Lifecycle Loops:

1. 01. /loop-1-plan — 🎯 Plan & Spec: Requirements, alignment, interactive grilling, .spec.md specs, and domain modeling.
2. 02. /loop-2-develop — ⚡ Develop & TDD: Isolated git branch, Red-Green-Refactor TDD cycle, parallel subagents, and cybersecurity guardrails.
3. 03. /loop-3-debug — 🔍 Debug & Verify: 4-phase bug diagnosis, wizard-ai debug check automated quality gates, and code review.
4. 04. /loop-4-refactor — 🏗️ Refactor & Optimize: Semantic code search (serena), clean code/DDD (ponytail), and token compression (sqz, caveman).
5. 05. /loop-5-release — 🚀 Release & Learn: Clean merge to main, SemVer versioning (auto-release), npm publishing, user handoff, and MEMORY.md persistent learning.

🛩️ AI Proxy (Cockpit Tools) & Pi Integration

Wizard-AI seamlessly integrates with Cockpit Tools via the wizard-ai proxy to bypass Gemini free-tier rate limits across multiple accounts and route traffic from the pi-coding-agent.

1. Install Proxy Dependencies

   wizard-ai proxy install
   

2. Add / Import Accounts You have two ways to add accounts to the proxy rotator:

   Option A (Manual OAuth): Add a Google account directly by signing in:

   wizard-ai proxy login
   

   Option B (Cockpit Tools Auto-Sync): Securely extract your refreshTokens from the local Cockpit Tools database (automatically decrypts AES-256-GCM tokens) and inject them into the proxy's accounts.json:

   wizard-ai proxy provision
   

3. Configure Pi Agent (pi) To automatically configure the Pi agent to route all its Google provider traffic through your local proxy:

   wizard-ai proxy pi-config
   

4. Start the Proxy Daemon To start the proxy as a background daemon (auto-starts on PC boot):

   wizard-ai proxy enable
   

📚 Included Skills & Repositories Registry

All tools and skills managed by Wizard-AI are open source. Here is the complete list of managed repositories:

🤖 Autonomous Agent Frameworks & Runtimes

• earendil-pi: Pi Agent Framework
• ecc: Enhanced Claude Code
• caveman: Caveman behavioral compression
• goodcode: Multi-agent orchestration
• openhuman: OpenHuman agent harness
• qwenpaw: QwenPaw agent scope
• syke: Syke autonomous agent
• mem0: Mem0 persistent memory
• personal-graph: Personal knowledge graph
• pi-config: Vekexasia pi agent configuration
• pi-cockpit-tools: Cockpit Tools multi-account & rotator extension for Pi

⚡ CLI Tools & Context Squeezers

• sqz: Token compression CLI
• llmlingua: Prompt compression (Microsoft)
• flashrank: Document re-ranking
• serena: Semantic code intelligence
• graphify: Knowledge graph builder
• litellm: Universal LLM proxy
• markitdown: File-to-Markdown converter
• mermaid-cli: Mermaid diagram CLI
• spec-kit: Spec-driven development
• cli-anything: Multi-modal CLI
• cli-printing-press: CLI printing press
• repodocs: Source-cited AI wiki generator
• pi-cockpit-proxy-setup: Interactive installer for Pi & Cockpit Tools proxy

🧩 Native LLM Prompt Skills & Packs

• antigravity-awesome-skills: Antigravity skill pack
• awesome-agent-skills: Community skill collection
• cybersecurity-skills: 754 cybersecurity skills
• system_prompts_leaks: Leaked system prompts corpus (ChatGPT, Claude, Gemini, Grok) for prompt security research
• engineering-excellence: Framework-agnostic SDD/TDD engineering standard
• stitch-skills: Google Stitch design skills
• design.md: Design system spec
• book-to-skill: Book-to-skill converter
• wiki-brain-skill: Wiki knowledge base
• impeccable: Impeccable standards
• last30days-skill: Last 30 days research
• claude-blog: AI blog writing
• claude-seo: SEO analysis plugin

🧠 Memory, Context & Knowledge Graph

• engram: SQLite-backed agent memory
• turbovec: TurboVec vector DB
• zvec: ZVec vector DB
• headroom: Headroom context proxy

🎨 Frontend Frameworks & UI Toolkits

• aionui: AionUI desktop harness
• phantom-ui: Phantom UI components
• mengto-skills: MengTo UI/UX design skills
• infographic: Infographic generator
• kinetics-ui: Spring-physics micro-interactions
• easy-vibe: Easy Vibe multi-modal

🖥️ Graphical Apps, Desktop & Media Services

• voicebox: Voicebox audio processor
• omnivoice-studio: OmniVoice Studio
• supertonic: Supertonic audio tools
• hyperframes: HeyGen video generation
• wslens: WSLens GUI backend
• pocketbase: PocketBase realtime DB
• trailbase: TrailBase realtime DB
• go-whatsapp: WhatsApp REST bridge
• wuzapi: WuzAPI WhatsApp REST
• openwa: OpenWA WebSocket engine
• cockpit-tools: Cockpit local proxy

🏗️ Starter Templates & Benchmarks

• express-typescript-starter: Express+TS starter
• aisuite: AI benchmark framework

🤝 Contributing & Skills Sync

Whenever you write a new skill or modify an existing one in ~/.gemini/config/skills/, it is automatically backed up into the Git repository when running:

wz-ai-sync-skills

⚖️ License

AGPL-3.0-only © darkrei08

🚀 Real-World Agentic Use Cases

Wizard-AI isn't a chatbot; it's a workforce. Here is what your terminal can autonomously achieve by combining the built-in skills:

1. 🛡️ Autonomous Pentesting & Security Hardening

Skills Used: strix, cybersecurity, crowdsec-skill, ECC Instead of running a basic linter, Wizard-AI deploys an autonomous hacker agent (strix) that attempts to exploit your codebase, generates proofs-of-concept, and rewrites the vulnerable code using strict NIST/OWASP protocols.

2. 🎨 "Anti-Slop" UI/UX Frontend Engineering

Skills Used: taste-skill, hallmark, mengto-skills, kinetics-ui Vanilla AIs generate generic, "bootstrap-looking" web pages. Wizard-AI reads your brief, enforces strict typographic rules, applies asymmetric layouts, and implements physics-based micro-interactions (kinetics-ui), outputting premium, agency-tier frontend code.

3. 🕸️ Deep Semantic Architecture Refactoring

Skills Used: serena, codebase-memory-mcp, 0-loop-engine Don't ask the AI to "read this file". Wizard-AI queries the Abstract Syntax Tree (AST) via Serena, creates an interactive knowledge graph (personal-graph), and refactors circular dependencies across 50+ files simultaneously without losing context.

4. 📈 SEO Research & Autonomous Blogging Pipeline

Skills Used: claude-seo, claude-blog, lightpanda Need growth? The orchestration dispatches background agents to scrape live web data via stealth browsers (camofox, lightpanda), runs an E-E-A-T SEO audit, and generates high-ranking semantic clusters and articles autonomously.

⚡ The Ultimate Agentic Arsenal (Wizard-AI vs Vanilla AI)

Wizard-AI isn't just a collection of prompts. It integrates the absolute best-in-class open-source projects to turn generic LLMs into an Agentic Operating System.

🧠 Mandatory Multi-Agent Workflows

By default, any agent launched under the Wizard-AI environment is strictly bound to Infrastructure-as-Code (IaC) principles. Complex tasks are strictly prevented from being executed monolithically in the main thread. Instead, they trigger asynchronous fan-outs using parallel() and subagent pools, performing adversarial reviews before any code is released.