GeniusBot — Desktop Cockpit for AI Agents

PyPI - Version GitHub Repo stars GitHub contributors PyPI - License

Version: 3.45.0

Documentation — The architecture overview, security boundaries, quick-start guidance, and the GeniusBot concept registry are maintained in the official documentation.

GeniusBot is the premium, unified space cockpit and visual control deck built on top of the agent-utilities powerhouse backend. It integrates all 37+ specialist agent and MCP packages from our multi-agent ecosystem into a single-pane-of-glass user interface, offering 1-click execution, embedded hybrid terminals, zero-nesting visual layouts, and a zero-trust hardware protection layer.

🌐 Overview

GeniusBot provides a centralized graphical cockpit designed to eliminate tedious click-through fatigue. It maps specialist agent parameter schemas directly to custom QSS-themed form widgets on the fly.

Operators can trigger actions, monitor running terminal inputs via the embedded agent-terminal-ui, and secure dangerous CLI calls using the Zero-Trust Tool-Guard interceptor.

✨ Features

Zero-Nesting Dynamic UI: Navigation categorized into flat category menus (Dashboard, Infra, Media, Productivity, Research).
Dynamic Card Schema Grid: PySide6 widgets are built automatically from specialist agent tool specifications.
Embedded Hybrid Terminal: Hosts local xterm.js to run interactive terminal loops directly in the cockpit.
Zero-Trust Security Tool Guard: Prompts native authorization dialogs to review arguments before executing dangerous mutations.
Runnable Background Workers: Utilizes thread pools (QThreadPool) to prevent GUI freezes during execution loops.
Visual Trading Dashboard: Snappy native C++ charting engine (PySide6.QtCharts) with OHLCV candlestick/line toggles, strategy indicator overlay crossovers (MACD/RSI), orderbook bids/asks depth volumes, and thread-safe crypto news feeds.

🏛️ Architecture

GeniusBot is engineered as a lightweight PySide6 GUI client wrapper around the agent-utilities logic engine.

graph TD
    subgraph GUI ["GeniusBot Cockpit (PySide6)"]
        Sidebar["Left Category Sidebar"]
        GridDeck["Central Dynamic Card Grid"]
        ToolGuard["Tool Guard Modal Interceptor"]
        TerminalPanel["xterm.js WebEngine Panel"]
    end

    subgraph Backend ["agent-utilities Powerhouse"]
        Discovery["Agent Specialist Discovery"]
        Executor["Background Agent Worker Loop"]
        KG["Epistemic Knowledge Graph"]
    end

    Sidebar --> GridDeck
    GridDeck -->|Introspect Schemas| Discovery
    GridDeck -->|Trigger Safe Action| Executor
    GridDeck -->|Sensitive Action| ToolGuard
    ToolGuard -->|Operator Approved| Executor
    TerminalPanel -.->|Interactive Terminal| Executor

Detailed architectural diagrams and component breakdowns are located in the Documentation Overview.

🛠️ Installation

1. Modern Virtual Environment (via uv)

Create a virtual environment and sync standard requirements:

# Setup virtual environment
uv venv

# Sync requirements
uv pip sync requirements.txt

2. Standard pip

Install standard stable packages:

pip install geniusbot

Install with all ecosystem plugins:

pip install geniusbot[all]

🌍 Environment Variables

GeniusBot can be configured using environment variables or a .env file in the project root:

Variable	Description	Default / Example
`QT_QPA_PLATFORM`	Headless Qt Platform (set to `offscreen` for CI/CD or Docker)	`offscreen`
`LANGFUSE_PUBLIC_KEY`	Langfuse Observability Public Key	`pk-lf-...`
`LANGFUSE_SECRET_KEY`	Langfuse Observability Secret Key	`sk-lf-...`
`LANGFUSE_HOST`	Langfuse Host URL	`https://cloud.langfuse.com`
`LOGFIRE_TOKEN`	Pydantic Logfire Telemetry Token
`TERM`	Terminal type for the embedded terminal emulator	`xterm-256color`
`_MEIPASS` / `_MEIPASS2`	PyInstaller temp directories for bundled app context	(Used internally)

🚀 Usage

Launch the desktop cockpit:

uv run geniusbot

To run in headless or virtual Linux environments (CI/CD):

QT_QPA_PLATFORM=offscreen uv run geniusbot

📦 Packaging & Executables

PyInstaller Compiling

Compiling GeniusBot as a single standalone executable:

python -m pip install --upgrade pyinstaller
git clone https://github.com/Knuckles-Team/geniusbot.git
cd geniusbot
python -m venv .venv
./.venv/Scripts/activate
python -m pip install -r ./requirements.txt
python -m pip install -r ./build-requirements.txt
python -m pip install --upgrade pandas scipy numpy pydantic
pyinstaller --name geniusbot `
  --log-level DEBUG `
  --onefile --windowed `
  --paths "./geniusbot" `
  --icon='./geniusbot/img/geniusbot.ico' `
  --recursive-copy-metadata=opentelemetry_api `
  --recursive-copy-metadata=opentelemetry_sdk `
  --recursive-copy-metadata=opentelemetry_exporter_otlp_proto_grpc `
  --exclude-module pygame `
  --exclude-module tkinter `
   ./geniusbot/geniusbot.py

Windows Setup Installer

Generate a Windows MSI setup package:

iscc "./setup.iss"

📚 Documentation References

For deep architectural guidelines and code documentation, explore:

docs/index.md — Documentation Entrypoint & Quickstart.
docs/overview.md — Detailed Architecture & Security Guardrails.
docs/concepts.md — Concept Registries (CONCEPT:GBOT-1.0 through 8.0).

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Metadata

Release files for geniusbot 3.45.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for geniusbot 3.45.0
File	Size	Uploaded
geniusbot-3.45.0.tar.gz	571.8 kB	Jun 17, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for geniusbot 3.45.0
File	Interpreter	ABI	Platform	Reset
geniusbot-3.45.0-py3-none-any.whl 168.8 kB Jun 17, 2026	Python 3	none	any	Details

Total release size: 740.6 kB

Release files / geniusbot-3.45.0.tar.gz

Download URL	geniusbot-3.45.0.tar.gz
Size	571.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`c92568a25369b4dcdc202980ad86ba08633e074550acc16f4016e00c58d58feb`
BLAKE2b-256 checksum How to use checksums	`9c4b1f3924d6d5ea77f1680b887b4c74369e6b72cf7ea067d05cec7e1a3094a3`
Upload date	Jun 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.4`

Release files / geniusbot-3.45.0-py3-none-any.whl

Download URL	geniusbot-3.45.0-py3-none-any.whl
Size	168.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`da858d4ca48376fed1be04135ea163b178c5d0da5dd48f709248b3cb6bc794f1`
BLAKE2b-256 checksum How to use checksums	`c5543c4e602f4f08ac9936c17476a70d75ff4b18e51d40aed1571160fe2c2ef3`
Upload date	Jun 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.4`