voxkage 1.1.10

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

VoxKage

Dynamic OS-Level AI Coordinator & Tri-Engine Router

Orchestrating the Antigravity CLI (agy), OpenCode CLI, and Claude Code to deploy an untethered, system-wide agentic capability core.

---

VoxKage is an open-source, system-wide local AI coordinator designed to operate directly on Windows and macOS. It functions as an orchestration layer and local daemon that maps, registers, and scaffolds a unified network of built-in Model Context Protocol (MCP) servers directly into your active front-end CLI. By acting as the central bridging hub, VoxKage routes resources, coordinates persistent tools, and manages background daemons seamlessly through the Antigravity CLI (agy), the OpenCode CLI, or Claude Code.

Unlike traditional API wrappers, VoxKage does not execute its own standalone LLM reasoning loop. Instead, it acts as the orchestrating launcher—scaffolding directories, injecting custom instructions, establishing background named-pipe IPC servers, and routing your prompts directly to your primary developer shells.

[Architecture] • [Control Center] • [MCP Servers Suite] • [Shield Security] • [Interactive Previews] • [Installation Guide] • [Plugin Setup] • [Development & Contribution] • [Troubleshooting]

---

📐 Architecture & Context Routing

VoxKage bridges its high-performance local MCP servers into your active development client. Depending on your configuration, VoxKage dynamically provisions the workspace and routes tools:

graph TD
    subgraph "VoxKage Orchestration Layer"
        A((voxkage Launch / CLI)) --> B{Engine Router}
        A --> C[System Tray Control Center]
        A --> D[Telegram Watcher Daemon]
        A --> E[Named-Pipe IPC Server]
    end

    subgraph "Context Routing & Scaffolding"
        B --> |interface_engine: 'antigravity'| F[Antigravity CLI Core]
        B --> |interface_engine: 'opencode'| G[OpenCode CLI Core]
        B --> |interface_engine: 'claude'| H[Claude Code CLI Core]
        
        F <--> |Auto-Inject GEMINI.md| I[~/.gemini/config/mcp_config.json]
        G <--> |Auto-Inject AGENTS.md| J[~/.config/opencode/opencode.json]
        H <--> |Auto-Inject CLAUDE.md| K[~/.opencode-starter/config.json]
    end

    subgraph "Shared Consciousness (MCP Web)"
        I <--> L[session_server.py]
        J <--> L
        K <--> L
        L <--> M[(Unified Vector RAG & Audit Logs)]
    end

    subgraph "Modular MCP Server Suite"
        I <--> N[Playwright Browser / OSControl / WebSearch / Cognitive Core]
        J <--> N
        K <--> N
    end

    style A fill:#06b6d4,stroke:#fff,stroke-width:2px,color:#fff
    style B fill:#8b5cf6,stroke:#fff,stroke-width:2px,color:#fff
    style L fill:#10b981,stroke:#fff,stroke-width:2px,color:#fff
    style F fill:#3b82f6,stroke:#fff,stroke-width:2px,color:#fff
    style G fill:#0ea5e9,stroke:#fff,stroke-width:2px,color:#fff
    style H fill:#e879f9,stroke:#fff,stroke-width:2px,color:#fff

Tri-Engine Routing Modes & Model Portfolios

VoxKage coordinates your session across three terminal environments, enabling you to exploit the strongest capabilities of each client:

• Antigravity CLI (agy): Pre-scaffolds and registers local sub-servers directly into the central mcp_config.json and injects custom instruction sets to ~/.gemini/GEMINI.md.
  • Core Developer Models: Leverages top-performing models including Gemini 3.5 Flash (high-speed commands), Gemini 3.1 Pro (complex operations), Claude 4.6 Sonnet (advanced logic), and Claude 4.6 Opus (high-context reasoning).
• OpenCode CLI: Registers MCP tools directly to opencode.json and maps instructions to AGENTS.md inside ~/.config/opencode/.
  • Core Developer Models: Configured for OpenCode's free high-efficiency OpenCode Zen portfolio, including DeepSeek v4 Flash.
• Claude Code CLI: Integrates local MCP endpoints directly with Anthropic's Claude Code launcher environment, pre-injecting safety overrides and system mappings into CLAUDE.md.
  • Core Developer Models: Uses OpenCode Zen free-tier API integrations to run Claude Code with robust local tool execution.

Shared Consciousness & Session Syncing

At the heart of the engine architecture is session_server.py. Whether you are typing in the Antigravity shell, OpenCode, or Claude Code, the session manager intercepts, structures, and logs active history and workspace contexts to a unified memory repository. All engines draw from the same vector RAG database and problem/solution registries, ensuring that context established in one CLI session is instantly recalled when you pivot to another.

---

🎨 The VoxKage Control Center & System Tray

VoxKage includes a canvas-rendered native Control Center that resides in your system tray, offering background daemon controls:

• Interactive Engine Selector: Switch your active CLI environment (Antigravity, OpenCode, or Claude Code) with a single click. VoxKage dynamically routes execution paths and configures local launcher templates.
• Gated Settings Sync: Autodetects configuration directories. Prevents polluting folders with irrelevant settings (e.g. gates write cycles to protect agy's configuration when opencode is active, and vice versa).
• Canvas-Rendered Smooth Toggles:
  • Autostart on Login: Registers VoxKage to launch on startup (autostart.py).
  • Safe Mode Shield Protocol: Restricts destructive shell and file system interactions.
  • Telegram Watcher Daemon: Persistently listens for remote directives (telegram_watcher.py).
  • Sandboxed Shell Tasks: Restricts terminal operations to safe user environments.
  • Audio/Toast Notifications: Emits auditory and system notifications (notify_server.py) upon task milestones.

---

⚙️ Modular MCP Server Suite

VoxKage ships with a suite of custom Model Context Protocol (MCP) servers engineered for local OS control and speed:

1. Cognitive Core Server (cognitive_core_server.py)

Provides self-correction, self-critique, and self-evolution gates. Under RULE ZERO, it parses tasks, sets domain-specific checklists, runs risk-prevention (pre_mortem), checks progress (checkpoint), conducts post-execution validation (reflect / verify), and updates behavioral memories (learn).

2. Headless WebSearch Server (websearch_server.py)

A high-performance, region-unlocked search utility using ddgs (DuckDuckGo Search) and article text extraction via trafilatura (HTML-to-markdown). Bypasses the overhead of Playwright browsers for simple queries. Supports:

• web_search & web_fetch (Headless search/read)
• web_search_parallel & web_fetch_parallel (Concurrent fetches)
• web_search_deep (Auto-fetch top search results concurrently)

3. Optimized RAG Indexer (rag_server.py)

A local semantic memory database using ChromaDB. Safety-hardened to prevent SQLite write-locks and sentence-transformer hangs:

• Size Guard: Skips text/code files >500KB and rich documents >5MB.
• Chunk Capping: Caps files to a maximum of 250 chunks.
• Exclusion Filters: Automatically ignores dependency lockfiles (package-lock.json, yarn.lock, etc.) and directories like vendor, .git, venv, and build caches.

4. Google Colab Workspace (ColabPlugin)

An integration server allowing developers to offload Python processing, dataset cleaning, and machine learning runs directly onto cloud kernels (create_colab_notebook, run_code_cell, get_notebook_content).

---

🛡️ The Shield Protocol (Security Systems)

Because VoxKage grants shell access and file manipulation to your active terminal agents, safety is governed by a three-layer security protocol inside shield.py:

1. Layer 1: Hard-Coded Exclusions (Never Overridable)
   • Protected Paths: Prevents modifications inside critical system folders such as C:\Windows, C:\Program Files, C:\Program Files (x86), and /System.
   • Forbidden Commands: Automatically intercepts and blocks dangerous commands (e.g., format, diskpart, rm -rf /).
   • Binary Deletions: Prohibits deletion of binary configurations (.sys, .dll, .exe) inside system paths.
2. Layer 2: Safe Mode Confirmation Gate
   • Controlled by the safe_mode configuration inside ~/.voxkage/config.json. When enabled, irreversible commands require interactive user validation (confirmed=True). Disabling it removes confirmation gates but keeps Layer 1 hard blocks active.
3. Layer 3: Auditing Pipeline
   • Every file delete, process termination, move, and shell execution is logged to a local audit log (~/.voxkage/brain/audit.log) with precise execution timestamps.

---

🖥️ Interactive Previews (Terminal Output Styles)

Here is what you will see when running VoxKage CLI commands:

voxkage init

Interactive startup configuration wizard and dependency checker:

  ┌────────────────────────────────────────────────────────────┐
  │  ✦  VoxKage v1.1.9 — First-Time Setup                      │
  │  ────────────────────────────────────────────────────────  │
  │  VoxKage supercharges your CLI into a living OS AI.        │
  │  This takes about 2 minutes.                               │
  └────────────────────────────────────────────────────────────┘

  ✓  Platform: Windows
  ✓  Data directory: C:\Users\AYUSH\.voxkage
  ✓  Created .env template
  ✓  Created default config
  ✓  Antigravity CLI found: C:\Users\AYUSH\AppData\Local\agy\bin\agy.exe

  [1/3] Capability Packs

  VoxKage core is already installed and ready. It includes:
    ✓  Agentic memory (SOUL system, problem/solution logs)
    ✓  ACE coding engine (step-by-step planning)
    ✓  Full OS control (open, edit, move, delete any file)
    ✓  System health, process management, date/time
    ✓  Office documents (Word, Excel, PowerPoint)
    ✓  Plugin credentials (Telegram, Gmail, Spotify, GitHub)
    ✓  Live internet access via agentic web search

  Choose packs to install (e.g. B,C or G or S): 

voxkage status

Real-time dashboard of system health, active environment path, capability packs, and connectors:

  ✦  VoxKage v1.1.9 — System Status
  ──────────────────────────────────────────────────

  CORE
    ✓  Interface Engine     Claude Code CLI — v0.2.9
    ✓  Brain directory      C:\Users\AYUSH\.voxkage

  CAPABILITY PACKS
    ✓  Core AI + OS Control       (always on)
    ✓  RAG Memory                 installed
    ✓  Vision & OCR               installed
    ✓  Browser Engine             installed
    ✓  PDF Conversion             installed

  INTEGRATIONS
    ✓  Telegram Bot               Connected
    ✗  Gmail                      voxkage plugins add gmail
    ✓  Spotify                    Connected
    ✓  GitHub                     Connected
    ✓  Firebase                   Connected
    ✓  Netlify                    Connected
    ✓  Supabase                   Connected
    ✓  ClickHouse                 Connected
    ✓  Sequential Thinking        Connected

  COMMUNITY PLUGINS
    (none installed)              voxkage plugins search <query>

voxkage plugins

List of registered services and credentials status:

  [✓] Telegram — Remote OS command execution, file transfer, and notifications.
  [ ] Gmail    — Read, draft, reply, and index emails directly from the agentic core.
  [✓] Spotify  — Dynamic search, playlist queuing, playback control, and environment triggers.
  [✓] GitHub   — Scan commits, manage repositories, fetch Action/CI workflows, and auto-submit PRs.

---

🛠️ Installation Guide

Prerequisites

• Python 3.10+
• Node.js & npm (Required to run OpenCode, Claude Code, and global web modules)
• pipx (Global CLI isolator)
• Antigravity CLI OR OpenCode CLI OR Claude Code

---

Step 1: Install pipx & Add to PATH

Ensure pipx is installed on your machine. If pipx is not recognized after installation, you must configure your environment variables:

1. Install via python:

   pip install pipx
   

2. Set up the PATH variables automatically:

   pipx ensurepath
   

3. IMPORTANT: Close your current terminal and open a brand-new shell window for the environment changes to take effect. If it still fails, manually add %USERPROFILE%\.local\bin to your system's PATH variable.

---

Step 2: Install VoxKage Globally

pipx install voxkage

Step 3: Run the Initialization Wizard

voxkage init

This builds configuration templates and links with active CLI endpoints.

Step 4: Install Extra Capability Packs

Install modular capabilities to handle advanced tasks:

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 modular capability packs in one step)

---

Step 5: Start the Daemon

• Interactive Terminal Developer Mode:

  voxkage
  

  Launches your configured shell client (agy, opencode, or claude) pre-populated with VoxKage MCP endpoints and custom global systems.

• Background System Tray Mode:

  voxkage tray
  

  Runs VoxKage persistently in your system tray, coordinating named pipes and polling the Telegram daemon.

---

🔌 Plugin Configuration Reference

Register credentials inside ~/.voxkage/.env or configure interactively via voxkage plugins add <name>.

Plugin Key	Env Variable Key Requirements	Purpose
telegram	TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID	Asynchronous remote workspace control.
spotify	SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET	Search tracks and control playlist states.
github	GITHUB_PAT	Manage Git repositories and fetch Actions logs.
gmail	Complete OAuth parameters configured interactively	Read, reply, and structure mail streams.
firebase	Configured via setup wizard	Manage Firebase databases and hostings.
netlify	Configured via setup wizard	Trigger deployments and monitor domain metrics.
supabase	Configured via setup wizard	Sync and coordinate Supabase database tables.
clickhouse	Configured via setup wizard	Query, organize, and write ClickHouse pipes.

---

💻 Local Development & Contribution

We welcome contributors! Here is how to configure a local development sandbox:

1. Clone the Codebase

git clone https://github.com/ayushdwivedi001/VoxKage.git
cd VoxKage

2. Set Up Virtual Environment

• Windows:

  python -m venv venv
  .\venv\Scripts\Activate.ps1
  

• macOS / Linux:

  python3 -m venv venv
  source venv/bin/activate
  

3. Install in Developer-Editable Mode

Install with all capability packs and development links enabled:

pip install -e .[full]

Note: Any edits to voxkage/cli.py, shield.py, or the files inside mcp_servers/ take effect immediately in your local environment when running voxkage from this shell.

---

⚙️ Local Configuration Schema

VoxKage settings reside at ~/.voxkage/config.json:

{
  "interface_engine": "antigravity",
  "autostart": false,
  "safe_mode": true,
  "claude_model": "deepseek-v4-flash-free"
}

• interface_engine: Selects your active client shell. Options: "antigravity", "opencode", or "claude".
• autostart: Launches the system tray Control Center automatically when the computer boots.
• safe_mode: Restricts or enables Layer 2 confirmation prompt gates.
• claude_model: Defines the default model selected for Claude Code runs.

---

❌ Troubleshooting & Common Errors

1. Upgrade Failures or Permissions Blocked ([Errno 13] Permission Denied)

• The Cause: The Control Center (pythonw processes) runs persistently in the background. Upgrading VoxKage via pipx will fail if system binaries are currently locked in memory.
• The Solution: Gracefully terminate locked processes via Windows PowerShell before running the force re-install:

  # Kill background VoxKage daemons and watchers
  Get-Process -Name "pythonw","python" -ErrorAction SilentlyContinue | Where-Object { $_.Path -like "*pipx*voxkage*" } | Stop-Process -Force
  Start-Sleep -Seconds 2
  
  # Force a clean reinstall from PyPI
  pipx install voxkage --force
  

2. Command voxkage Not Recognized / pipx PATH Failure

• The Cause: Your user environment variables do not map to the pipx binary installation target.
• The Solution: Run pipx ensurepath inside a terminal, then close all terminal windows. Open a fresh terminal window to reload the variables. If it still fails, manually open the Windows Environment Variables window and add %USERPROFILE%\.local\bin to your User PATH list.

3. Playwright Chromium Executable Missing

• The Cause: Playwright's local browser binaries have not been fetched.
• The Solution: Download isolated chromium dependencies inside the active environment:

  playwright install chromium
  

---

"Ready to coordinate the system, sir."
— VoxKage