🧙‍♂️ Wizard-AI

A complete ecosystem of AI CLI wrappers, token-optimization tools, and agent skills — usable globally by any AI agent (Antigravity, Claude Code, Gemini CLI, GitHub Copilot, Amp, etc.) and directly from your terminal.

🇮🇹 Leggi questo README in Italiano

✨ What is this?

Wizard-AI is a one-command setup that gives every AI agent on your machine access to the same set of productivity tools:

• 🗜️ Token compression — reduce context by up to 20x before sending to an LLM
• 🌐 Knowledge graphs — map any codebase into a queryable graph in minutes
• 🧠 Persistent memory — semantic memory that survives across AI sessions
• 📄 Document conversion — PDF, DOCX, XLSX → clean Markdown for LLM ingestion
• 🔍 Smart re-ranking — filter RAG passages by relevance before context injection
• 📈 Usage tracking — monitor token consumption and costs
• 🔗 LLM gateway — unified API for 100+ providers via LiteLLM
• 🛩️ Cockpit Tools Proxy — bypass free API limits by leveraging your active IDE subscription (on Windows, Linux, and macOS)

All tools are installed once and available to every AI agent through a shared skill system.

🚀 Quick Start

⚡ Option A — One command via npm (recommended)

If you have Node.js (≥ 14) and git installed, this works the same on Linux, macOS and Windows:

npx @darkrei08/wizard-ai-cli
# or 'npx @darkrei08/wizard-ai-cli --verbose' for detailed logs

The launcher clones the repository into ~/.wizard-ai and runs the platform installer (setup.sh or setup.ps1) automatically. Re-running the command updates an existing install. You can also install it as a global command:

npm install -g @darkrei08/wizard-ai-cli
wizard-ai

🔧 Option B — Manual install (3 steps)

To make you fully autonomous, follow these steps to install and start using the ecosystem:

1️⃣ Clone the Repository

Clone the repository to your local machine:

git clone https://github.com/darkrei08/Wizard-AI.git ~/wizard-ai
cd ~/wizard-ai

2️⃣ Run the Installer

Run the main setup script. It is designed to be completely non-interactive and handles all configurations automatically:

Linux / macOS:

chmod +x setup.sh
sudo ./setup.sh
# or 'sudo ./setup.sh --verbose' for detailed logs

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -File setup.ps1
# or add -VerboseMode for detailed logs

3️⃣ Verify Installation

Reload your shell to load the new environment variables, then launch the help menu:

source ~/.bashrc   # or source ~/.zshrc — on Windows simply open a new terminal
ai-help

You should see the list of commands.

4️⃣ Launch the Local Dashboard (Hub)

The ecosystem includes a beautiful graphical interface (Hub) to explore skills and view statistics (including the Cockpit Tools Tracker). You can open it from the terminal with the built-in wrapper, which will start a local mini-server and automatically open the browser:

ai-hub

Manual alternative to start the server:

python3 $WIZARD_AI_DIR/hub/api/server.py --port 9742
# Open http://localhost:9742 in your browser

🐳 Option C — Run via Docker (for Web GUI)

If you prefer to keep the web environment isolated, you can run the Dashboard via Docker. The container will automatically mount your host system volumes to read the correct telemetry data:

docker compose up -d

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

📊 Performance Benchmarks

To illustrate the immense value of the Wizard-AI toolkit, we've executed three prompts of varying complexity comparing the standard approach (raw prompt) versus the Wizard-AI approach (using ai-compress / ai-caveman / ai-graph).

Benchmark Results

| Difficulty Level | Task Description | Tokens (Standard) | Tokens (Wizard-AI) | Reduction (%) | Tools Used | | :--- | :--- | :--- | :--- | :--- | :--- | | Low | Simple Python script (Fibonacci up to 100) | In: 50Out: 200 | In: 40Out: 150 | ~25% | ai-prompt | | Medium | Extract & group 'OutOfMemory' exceptions from a 10K lines log | In: 25,000Out: 500 | In: 5,000Out: 200 | 80% | ai-compress + ai-squeeze | | High | Generate architecture & codebase for a Next.js e-commerce app | In: 15,000Out: 4,000 | In: 3,000Out: 1,000 | 78% | ai-graph + ai-caveman |

Why it matters:

• Cost Savings: Sending an 80% smaller context window directly translates to 80% lower API costs.
• Speed: Generating 1,000 output tokens takes significantly less time than generating 4,000, letting your AI respond in seconds instead of minutes.
• Accuracy: By filtering out noise with ai-compress and ai-rerank, the LLM hallucinates less and focuses on the actual problem.

⚙️ 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 (~/.ai-skills/venv).
3. Clones dependency repos: Downloads required helper repositories under ~/.ai-skills/.
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 ai-sync-skills to copy them to other agent folders.

🛠️ Available Commands

After installation, these commands are available in your terminal:

| Command | Tool | Description | |---|---|---| | ai-hub | Local GUI | Open the dashboard and marketplace in your browser | | ai-help | Hub | Show all available tools with usage examples | | ai-update | Updater | Manually pull latest updates for Wizard-AI (includes cross-platform desktop notifications) | | ai-graph [path] | Graphify | Build knowledge graphs. Automatically connects to Cockpit Tools to save API Keys! | | ai-compress --file f.txt | LLMLingua | Compress prompts/context up to 20x | | ai-compare "prompt" | aisuite | A/B test a prompt across multiple LLM models | | ai-rerank --query "X" | FlashRank | Re-rank passages by relevance | | ai-squeeze | Sqz | Compress CLI output / JSON / logs | | ai-convert document.pdf | MarkItDown | Convert any file to clean Markdown | | ai-mem store "text" | claude-mem | Store a persistent semantic memory | | ai-usage | GeminiUsage | Track token consumption and budget | | ai-sync-skills | Sync | Propagate skills to all AI agents | | book-to-skill doc.pdf | book-to-skill| Convert books/docs into AI skills | | litellm --port 4000 | LiteLLM | Unified LLM API gateway |

🏗️ Master Project Bootstrap

Wizard-AI now includes the master-project-bootstrap skill, the ultimate meta-skill for initializing and architecting production-ready projects.

By simply invoking this skill when starting a new project, your AI agent will automatically enforce:

• Clean Architecture & SDD/TDD (via spec-kit and test-driven-development).
• Dynamic Framework Selection (routing to express, nuxt, next.js, pocketbase, or zvec based on your project's complexity).
• Mandatory Living Documents (MEMORY.md, CHANGELOG.md, PROMPT.md, AGENT.md) to maintain perfect state and context across sessions.
• Skill Chaining (automating auto-workflow, scaffold, taste-skill, graphify, serena, auto-debug, and auto-release seamlessly).

You just need to provide your idea, and Wizard-AI will orchestrate the perfect setup.

🧠 How Skills Work

Skills are SKILL.md files that teach AI agents when and how to use a tool. Each agent reads its own skills directory:

| Agent | Skills Directory | |---|---| | Antigravity (Gemini CLI) | ~/.gemini/config/skills/ | | Claude Code | ~/.claude/skills/ | | Amp | ~/.config/amp/skills/ |

setup.sh installs skills once to ~/.gemini/config/skills/. Running ai-sync-skills then copies them to all other agent directories automatically.

Syncing Custom Skills

Whenever you write a new skill or modify an existing one, run:

ai-sync-skills

This script synchronizes your modifications back to your cloned repository under skills/ and propagates them to other agents.

📁 Project Structure

wizard-ai/
├── bin/                    # CLI wrapper scripts → deployed to ~/.local/bin/
│   └── windows/            # PowerShell ports of the wrappers (Windows)
├── skills/                 # SKILL.md definitions → deployed to agents
├── docs/                   # Reference guides and documentation
│   ├── WIKI.md             # 📚 Central Wiki of all skills & resources
│   └── security-prompts/   # AI-specific security audit prompts
├── local/                  # Ignored folder for personal config & cloned repos
├── setup.sh                # One-command installer (Linux / macOS)
├── setup.ps1               # One-command installer (Windows)
├── cli.js                  # npm launcher (npx wizard-ai-cli)
├── package.json            # npm package manifest (wizard-ai-cli)
├── CONTRIBUTING.md         # How to add new skills
├── LICENSE                 # AGPLv3
└── README.md               # This file

🔒 Security Audit Prompts

This repository includes a suite of professional security audit prompts specifically designed for AI-generated applications (vibe coding).

You can find them in the docs/security-prompts/ directory. They cover:

• Secrets and Environment Variables
• Database Security (RLS, SQLi)
• Authentication and Payments
• Frontend vulnerabilities
• Complete Final Audit Framework

Use them with a zero-context AI session to spot vulnerabilities before deploying.

🔧 The $WIZARD_AI_DIR Variable

After running setup.sh, your shell will have $WIZARD_AI_DIR set to the absolute path of your cloned repository.

echo $WIZARD_AI_DIR
# → /home/you/wizard-ai

On Windows it is stored as a user environment variable:

echo $env:WIZARD_AI_DIR
# → C:\Users\you\wizard-ai

This allows skills and wrappers to reference the repo portably, regardless of where you cloned it.

🤝 Contributing

See CONTRIBUTING.md for instructions on adding skills, wrappers, and improvements.

🙏 Credits

Wizard-AI integrates these excellent open-source projects:

• Graphify
• LLMLingua
• FlashRank
• MarkItDown
• Sqz
• claude-mem
• GeminiUsage
• LiteLLM
• Serena
• ECC
• book-to-skill
• Cockpit Tools - Local proxy to slash LLM API costs

⚖️ License

AGPLv3 License — use freely, fork, and contribute.