voxkage 1.1.6

VoxKage - OS-level Agentic AI Assistant. Autonomous, Persistent, Aware.

VoxKage

The Sovereign OS-Level Agentic Brain

Commanding the Antigravity CLI (agy) and OpenCode CLI to deploy an untethered, system-wide living AI core.

---

VoxKage is a massive paradigm shift in local AI capability. It is not an IDE chatbot or a localized command wrapper—it is a sovereign, system-wide living Agentic OS Brain. By leveraging the advanced execution engines of the Antigravity CLI (agy) or the **OpenCode CLI (opencode)** as its conversational frontends and toolkits, VoxKage breaks the AI out of standard directory confinements, deploying a unified honeycomb of intertwined MCP servers to act as your PC's central, self-learning mind.

[The Architecture] • [Core Capabilities] • [Unified Integrations] • [Control Center] • [Quick Start] • [Updating]

---

🧠 The Innovation: Sovereign OS Mastery & Dual-Engine Routing

The Standard AI Limitation

Standard AI command-line assistants are heavily restricted. They are confined strictly to the folders where they are executed. If you command them to "Inspect my running local databases, compile a patch for a broken backend route in a separate directory, download the correct compiler from the web, and alert my Telegram when it's done," they fail. They are blind, unable to orchestrate processes, and isolated from your desktop and remote devices.

The VoxKage OS Evolution

VoxKage redefines local AI orchestration. By taking direct command of Antigravity CLI (agy) or the OpenCode CLI, VoxKage acts as the overarching System Mind, using the local runtime environments to interface with your OS on a deep level. It merges its own 18+ core/plugin MCP engines with your local configuration, automatically mapping and injecting them depending on which engine you choose.

VoxKage doesn't merely trigger commands; it orchestrates full workflows. It will launch a Playwright browser, capture a desktop screenshot, extract DOM CSS styles, execute repairs, test process ports via native PowerShell, and sync with your personal remote Telegram chat—governing its own steps in a fluid, self-correcting cognitive loop.

graph TD
    subgraph "VoxKage Sovereign OS Brain"
        A((VoxKage Core Directive)) --> B{Agentic Reasoning Loop}

        subgraph "Self-Healing & Orchestration"
            B <--> C(ACE: Dynamic Planning)
            B <--> D(DOM Verification & GUI Thinking)
            B <--> E(Sovereign RAG & Memory)
        end
    end

    subgraph "Unified Dual-Engine Core"
        C <--> |Dynamic Scaffolding| F[Global MCP Registry]
        F <--> |~/.gemini/config/mcp_config.json| G[Antigravity CLI]
        F <--> |~/.config/opencode/opencode.json| H[OpenCode CLI]
        B <--> |Dynamic Launcher Router| I{Active Terminal CLI}
    end

    subgraph "The Honeywell MCP Web"
        C <--> J[Playwright Browser Engine]
        C <--> K[Codebase AST Skeletor]
        D <--> L[Native Shell & FileOps]
    end

    subgraph "Omnipresent Bridges"
        B <--> M[Telegram Remote Control]
        B <--> N[Gmail / Spotify / GitHub]
    end

    style A fill:#06b6d4,stroke:#fff,stroke-width:2px,color:#fff
    style B fill:#8b5cf6,stroke:#fff,stroke-width:2px,color:#fff
    style C fill:#10b981,stroke:#fff,stroke-width:2px,color:#fff
    style I fill:#0ea5e9,stroke:#fff,stroke-width:2px,color:#fff

---

✨ Core Capabilities & Engineering Specs

⚙️ 1. The Agentic Coding Engine (ACE)

VoxKage runs an autonomous, 5-phase software development pipeline. It never guesses or writes blind changes:

• AST Skeleton Mapping: Extracts 40-line structural metadata from 2000-line source code files. This results in 95% token savings while retaining total architectural context.
• Dynamic Planning: Maintains a living step-by-step checklist (task.md) in its brain.
• Self-Healing Loop: Compiles, tests, and validates code changes. If a syntax or runtime check fails, VoxKage captures the log output, dynamically diagnoses the root cause, and writes a self-corrective patch automatically.

🌐 2. Deep Web & Desktop Automation

The internet and operating system are completely open to VoxKage. It launches an isolated, headless Playwright engine to:

• Inspect active layouts, extract computed CSS properties, and debug complex UI animations.
• Run semantic web queries, crawl official software downloads, extract direct URLs, execute the installer, and verify process health.
• Manipulate native applications via simulated mouse interactions, keyboard typing, and shortcut keys.

🌉 3. The Omnipresent Bridges

VoxKage establishes a permanent, secure remote control bridge. Even when away from your computer, you can communicate with VoxKage through your custom Telegram bot:

You (Telegram): "My production deploy failed. Fetch the latest git logs, find the error, patch it, run unit tests, and push the commit."

VoxKage: "Right away, sir. Pulling logs, writing a patch, and running tests... [1 minute later] Patch compiled successfully and pushed to main. Here is the verified test log."

---

🔌 Unified Integrations (10 Built-In Plugins)

VoxKage features native real-time connection mapping. The moment you execute voxkage status, it dynamically queries the active state and configuration of all 10 built-in plugins:

Integration	Type	What it unlocks
Telegram Bot	Communication	Complete remote OS command execution, file transfer, and notifications.
Gmail	Utility	Read, draft, reply, and index emails directly from the agentic core.
Spotify	Media	Dynamic search, playlist queuing, playback control, and environment triggers.
GitHub	Code	Scan commits, manage repositories, fetch Action/CI workflows, and auto-submit PRs.
Firebase MCP	Development	Manage Firebase databases, query resources, check logs, and deploy rules.
Netlify MCP	Deployment	Monitor hosting sites, configure deployments, read team stats, and deploy code.
Supabase MCP	Database	Manage databases, list projects, view migration history, and execute SQL statements.
Chrome DevTools	Web	Audit performance, click elements, fill forms, check networks, and audit web views.
ClickHouse MCP	Database	Query analytics databases, fetch organization details, and audit pipes.
Sequential Thinking	Reasoning	Advanced multi-step mathematical and algorithmic thinking logic.

[!NOTE] Coexistence Engine: When initialized, VoxKage automatically detects pre-existing MCP integrations configured inside your Antigravity IDE setup and merges them safely inside its global registry, ensuring you have a synchronized collection of tools in both your IDE and your CLI sessions.

---

🎨 The VoxKage Control Center

VoxKage features a gorgeous, high-fidelity native Tkinter Control Center accessible right from your system tray.

• Dynamic Interface Provider Selector: Zero comboboxes. Switch between the premium Antigravity CLI (agy) (ideal for AI subscription accounts) and the flexible OpenCode CLI (ideal for free-tier users connecting custom API keys via OpenCode's /connect command) with a single, responsive click.
• Engine-Aware Settings Sync: Automatically gates Visual Themes and Notification configurations. Gated write cycles prevent writing irrelevant properties to Antigravity's settings directory when OpenCode is selected, while maintaining global VoxKage-level toast notifications and unified ASCII startup banner color schemes.
• Custom Smooth Slide Toggles: Canvas-rendered, animated round switches with snapping state logic (Autostart on Login, Safe Mode Shield Protocol, Telegram Watcher Daemon, Sandboxed Shell Tasks, Toast/Audio Notifications).
• Dynamic Theme Subtitle Hints: The theme card sub-label automatically shifts based on your active interface, informing you that OpenCode manages terminal color themes natively, while keeping the picker active to style VoxKage's beautiful CLI startup banner.

---

🛠️ Quick Start: Install in 60 Seconds

VoxKage is packaged as a globally executable Python distribution. No complex source code compilation is required.

Prerequisites

Ensure the following runtimes are active on your Windows machine:

1. Python 3.10+ (python --version)
2. pipx (pipx --version)
3. Antigravity CLI (agy --version) OR OpenCode CLI (opencode --version)

If you need to install pipx first:

pip install pipx
pipx ensurepath

---

Step 1: Install VoxKage

pipx install voxkage

---

Step 2: Initialize the Brain

voxkage init

This launches the setup wizard, which automatically:

• Creates the central data directory at ~/.voxkage.
• Scaffolds the integration environment secrets file (~/.voxkage/.env).
• Configures system prompts and injects the global MCP server registrations directly into ~/.gemini/config/mcp_config.json (for Antigravity) and ~/.config/opencode/opencode.json (for OpenCode).
• Configures shared visual parameters.

---

Step 3: Add Capability Packs

The base package remains lightweight (~80 MB). Heavy dependencies are opt-in capability packs that VoxKage resolves, downloads, and isolates inside the pipx environment automatically:

voxkage install <pack>

• voxkage install browser (Playwright web browser automation, DOM styling tools - Highly Recommended)
• voxkage install rag (ChromaDB Vector Store, embedding models, semantic codebase indexes)
• voxkage install vision (OpenCV, screen OCR scanning, visual validations)
• voxkage install docs_plus (Word to PDF compilers, Excel data parsing dependencies)
• voxkage install full (Installs all 4 premium capability packs in a single command)

---

Step 4: Launch the Sovereign Core

• To run an interactive terminal agentic session:

  voxkage
  

  VoxKage will automatically detect your selected interface engine (Antigravity or OpenCode) and route your session seamlessly, printing the unified ASCII startup banner styled according to your active theme.

• To start the background Control Center & Telegram daemon:

  voxkage tray
  

  Once launched, you can close your shell. VoxKage is alive in the system tray, listening for phone directives and remotely managing your operating system.

---

🔄 Updating & Upgrading

To update your global VoxKage distribution to the latest PyPI release:

pipx upgrade voxkage

Stuck Upgrades & Lock Resolution

Since the tray Control Center and Telegram watcher daemons run persistently in the background as pythonw processes, they can lock virtual environment files and cause permission failures ([Errno 13] Permission Denied) during pipx upgrades.

If this happens, run this clean lock-breaking pipeline in Windows PowerShell to gracefully terminate all active instances and force reinstall the latest version:

# 1. Kill any active background VoxKage and Python runners
Get-Process -Name "pythonw","python" -ErrorAction SilentlyContinue | Where-Object { $_.Path -like "*pipx*voxkage*" } | Stop-Process -Force
Start-Sleep -Seconds 2

# 2. Force reinstall voxkage cleanly from PyPI
pipx install voxkage --force

---

🔌 Command Reference

Command	Action
voxkage	Launch an interactive agentic session (seamlessly routed to Antigravity or OpenCode).
voxkage init	Scaffold directories, environment config, and global MCP registrations.
voxkage status	Show real-time dashboard of plugins, capability packs, active interface engine, and OS health.
voxkage tray	Run the system tray Control Center icon and activate the Telegram daemon.
voxkage install <pack>	Add modular capability packs (browser, rag, vision, docs_plus, full).
voxkage plugins	Inspect registered plugin states.
voxkage plugins add <name>	Interactively configure credentials for Gmail, GitHub, Spotify, and Telegram.
voxkage --version	Output current installed release version.

---

"I am ready, sir."
— VoxKage