[Quick Start] • [Supported Engines] • [Capabilities] • [CLI Commands] • [Contributing] • [Troubleshooting]

🚀 Quick Start (60 Seconds)

1. Install VoxKage

Install globally using pipx (recommended) or pip:

pipx install voxkage

2. Initialize Environment

Run the interactive setup wizard:

voxkage init

The setup wizard automatically detects your installed coding CLIs, configures persistent storage at ~/.voxkage/, and scaffolds all MCP server registrations across your providers.

3. Launch Your Preferred CLI

Start coding with your active engine:

voxkage             # Launches configured default interface
voxkage status      # Health check all 15 MCP servers & active integrations
voxkage tray        # Launches the background system tray manager

⚡ Supported Interface Engines

VoxKage unifies your toolset and memory across 4 major coding assistants. You can use any one of them (or all four):

[!NOTE] If you have at least one engine installed, VoxKage works immediately. Missing engines are shown during voxkage init with their one-line install command.

🧠 Core Capabilities & Architecture

┌────────────────────────────────────────────────────────────────────────┐
│                          VOXKAGE COORDINATOR                           │
│      Antigravity (agy) │ OpenCode │ Claude Code │ DeepSeek Harness     │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
    ┌───────────────────────────────┴───────────────────────────────┐
    ▼                                                               ▼
┌──────────────────────────────────────┐  ┌──────────────────────────────────────┐
│       Core MCP Servers (15)          │  │        Active Integrations (8)       │
├──────────────────────────────────────┤  ├──────────────────────────────────────┤
│ • voxkage-cognitive-core (Reasoning) │  │ • Telegram Remote Daemon             │
│ • voxkage-memory (Soul DB & TF-IDF)  │  │ • Gmail Automation                   │
│ • voxkage-rag (Local SQLite FTS5)    │  │ • Spotify Playback Control           │
│ • voxkage-websearch (Fast DuckDuckGo)│  │ • GitHub Actions & Commits           │
│ • voxkage-browser (Playwright)       │  │ • Netlify & Supabase MCP             │
│ • voxkage-system & oscontrol         │  │ • Sequential Thinking MCP            │
│ • voxkage-devserver & coding (ACE)   │  │ • Google Colab Integration           │
│ • voxkage-gui, notify, file, session │  │                                      │
└──────────────────────────────────────┘  └──────────────────────────────────────┘

1. Dynamic Recursive Self-Improvement (voxkage-cognitive-core)

Instead of rigid checklists, VoxKage uses a dynamic, model-driven self-improvement loop:

• cognitive_think: Multi-step reasoning that automatically retrieves relevant past incident fixes & prevention rules from Soul Memory before code is edited.
• verify_workspace: Deep compiler and syntax validation across Python (py_compile), JavaScript/TypeScript (node --check), HTML (extracts <script> modules for syntax validation), and JSON/YAML.
• record_incident: Logs concrete bugs, root causes, solutions, and prevention rules at the end of a task into ~/.voxkage/cognitive/incidents.jsonl and SQLite memory.
• cognitive_optimize: Displays active prevention rules and memory index health.

2. Two-Tier Memory Architecture

• Tier 1 (Lean Prompt Injection): Personal identity and core user preferences are injected into CLAUDE.md / GEMINI.md (~1.5k chars max). Never triggers 40k context limit warnings.
• Tier 2 (Dynamic SQLite & RAG): Problem/solution logs, bug resolutions, and technical learnings are stored in ~/.voxkage/memory.jsonl and rag_database.db, queried dynamically on-demand via search_memory("<keywords>").

3. Remote Telegram Control

Control and query your desktop assistant remotely from your phone:

voxkage plugins telegram setup   # Configure Telegram bot token & chat ID

🛠️ CLI Reference

voxkage init              # Interactive setup & multi-engine scanner
voxkage status            # Inspect active MCP servers, engines, and integrations
voxkage tray              # Start the background system tray manager
voxkage rag index <path>  # Index a directory into SQLite FTS5 RAG database
voxkage rag search <q>    # Search indexed documents via full-text search
voxkage plugins list      # Show installed community and core plugins
voxkage plugins setup <p> # Configure plugin credentials (telegram, spotify, etc.)
voxkage upgrade           # Check and upgrade to the latest VoxKage release

💻 Local Development & Contributing

We welcome community contributions, bug fixes, and new plugins!

1. Clone the Repository

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

2. Create Virtual Environment & Install Dependencies

python -m venv venv

# Windows:
.\venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

pip install -e .
pip install build twine pytest

3. Verify Syntax & Run Tests

python -m py_compile voxkage/cli.py voxkage/mcp_servers/cognitive_core_server.py
python -m voxkage.cli status

4. Submitting a Pull Request

1. Fork the repository and create a feature branch (git checkout -b feature/amazing-feature).
2. Commit your changes (git commit -m "feat: add amazing feature").
3. Push to your branch (git push origin feature/amazing-feature).
4. Open a Pull Request on GitHub.

❓ Troubleshooting

1. Permission Denied on Windows during pipx upgrade

If Windows locks python.exe while VoxKage background tasks or system tray are running:

Get-Process -Name "pythonw" -ErrorAction SilentlyContinue | Stop-Process -Force
Start-Sleep 2
pipx install voxkage --force

2. Re-scaffold MCP Server Registrations

If you installed a new engine (e.g. DeepSeek Harness or OpenCode) after initial setup:

voxkage init

This re-scaffolds the schema files and configurations for all detected engines.

📄 License

Distributed under the Apache 2.0 License. See LICENSE for more information.