🚀 Antigravity Telegram Control Hub

Secure, cross-platform remote control system and Telegram bridge for Google Antigravity IDE and Host System.

AI Control Hub connects your Linux/Windows workstation running Google Antigravity IDE to a dedicated Telegram Bot, giving you secure, instant remote access to IDE sessions, AI conversations, quota status, system metrics, hardware control, and remote command execution — all formatted using Telegram Bot API 10.3 Native Rich Markdown.

📑 Table of Contents

• Key Features
• Architecture & Workflow
• Monorepo Package Structure
• Prerequisites
• Installation & Quick Start
• Configuration (.env)
• Telegram Bot Commands & Interactive Menu
• Telegram Bot API 10.3 Native Rich Markdown
• Security & Authentication
• Development & Testing
• License

✨ Key Features

🧠 Antigravity IDE Deep Integration

• Live Transcript Reader (/chat): Reads real-time conversation history directly from Antigravity Brain (~/.gemini/antigravity/brain/<session>/transcript.jsonl), displaying the latest user prompt and AI assistant response with Markdown formatting.
• Session Manager (/sessions): Scans and lists all active and archived Antigravity IDE sessions with timestamps and message counts.
• AI Quota Tracking (/quota): Fetches model quota limits, usage percentages, and reset countdowns (Claude 3.7 Sonnet, Gemini 2.5 Flash, etc.).
• Remote Prompt Dispatch (/ask <prompt>): Send prompts and instructions directly into the running IDE workspace from Telegram.

🖥️ Remote Host & Hardware Control

• Instant Screen Lock & Unlock (/lock, /unlock):
  • Ultra-fast targeted session unlock (<30ms) via loginctl unlock-session <SID> combined with GNOME ScreenSaver D-Bus shield dismissal.
  • Zero typing or password prompts required from the authorized owner.
• Hardware Health (/health or 💻 Sys Health): Real-time CPU, RAM, Disk usage, Thermal temperatures, and Laptop Battery status.
• Live Desktop Screenshot (/screenshot): Captures the current active desktop display and sends it directly to your Telegram chat.
• Process Management (/tasks, /top): Formats running processes into Telegram native bordered grid tables with inline one-click kill buttons.
• Remote Shell & File Explorer (/cmd, /files): Execute terminal commands and navigate workspace files remotely.

📱 Modern Telegram Experience (Bot API 10.3)

• Pure native Rich Markdown Style (sendRichMessage) — no HTML tags or fragile escaping.
• Native Bordered Grid Tables (is_bordered, is_striped).
• Yellow syntax highlighting (==marked text==), collapsible quotes, spoilers (||spoiler||), and clean headings.
• 10-button persistent Quick Action Keyboard.

🏛️ Architecture & Workflow

flowchart TD
    TG[📱 Telegram User / App] -->|Bot API 10.3 Webhook / Polling| CG[☁️ Cloud Gateway :3000]
    
    subgraph Host Workstation
        LA[🤖 Local Agent Hub Runner]
        AGY[🧠 Antigravity IDE & Brain]
        OS[💻 Linux / Windows OS & Hardware]
        
        LA -->|Outbound Authenticated WebSocket| CG
        LA <-->|Loopback IPC :47110| AGY
        LA -->|systemctl / loginctl / dbus| OS
        LA -->|JSONL Parser| AGY_BRAIN["~/.gemini/antigravity/brain/"]
    end

1. Outbound WebSocket Tunnel: The local-agent establishes an outbound WebSocket connection (ws://.../v1/agent/connect) to cloud-gateway. No open inbound router ports or public IPs required.
2. Loopback IPC Bridge: Listens on 127.0.0.1:47110 for bidirectional communication with the IDE extension or background scripts.
3. Brain JSONL Engine: Parses transcript.jsonl step trajectories to stream agent responses without interfering with the IDE UI.

📦 Monorepo Package Structure

The repository is managed with Turborepo and pnpm workspaces:

📋 Prerequisites

• Node.js: v20.x or v22.x (LTS recommended)
• pnpm: v9.x or v10.x
• Linux (Ubuntu / Debian / Fedora / Arch) or Windows 10/11
• Telegram Bot Token: Created via @BotFather
• Telegram User ID: Your personal numerical ID (from @userinfobot)

⚡ Installation & Quick Start

1. Clone & Install Dependencies

cd "ai-control-hub"
pnpm install

2. Configure Environment Variables

Create a .env file in the root directory (or copy from .env.example):

cp .env.example .env

Edit .env:

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN="your_bot_token_from_botfather"
TELEGRAM_ALLOWED_USER_IDS="123456789"

# Networking & Ports
PORT=3000
HOST="127.0.0.1"
WS_PORT=3000
EXTENSION_IPC_PORT=47110

# Security Secrets
JWT_SECRET="super-secret-jwt-key-32-chars-minimum"
AGENT_SHARED_SECRET="super-secret-agent-token-32-chars-min"

# Single User Personal Mode
AUTO_BIND_SINGLE_DEVICE="true"
DEFAULT_DEVICE_ID="dev_primary"
DEFAULT_DEVICE_NAME="workstation (linux)"

3. Build Monorepo

pnpm build

4. Start the Hub (All-in-One Daemon)

pnpm start:hub

Tip: You can also run individual services during development:

pnpm --filter @hub/cloud-gateway dev
pnpm --filter @hub/local-agent dev

⌨️ Telegram Bot Commands & Interactive Menu

Persistent Menu Keyboard

┌─────────────────────┬─────────────────────┐
│ 🖥️ Status           │ ⚡ Quota            │
├─────────────────────┼─────────────────────┤
│ 📸 Screenshot       │ 📁 Files            │
├─────────────────────┼─────────────────────┤
│ 💬 Chat             │ 📜 Sessions         │
├─────────────────────┼─────────────────────┤
│ 💻 Sys Health       │ 🔒 Lock Screen      │
├─────────────────────┼─────────────────────┤
│ 📋 Tasks            │ ❓ Help             │
└─────────────────────┴─────────────────────┘

Available Slash Commands

🎨 Telegram Bot API 10.3 Native Rich Markdown

AI Control Hub utilizes the Telegram Bot API 10.3 sendRichMessage format. This provides substantial benefits over legacy MarkdownV2 and HTML:

1. No Escaping Conflicts: No more backslash escaping bugs with _, *, [, ], (, ).
2. Native Tables: Standard Markdown tables automatically format as Telegram bordered grid tables:

   | Model | Used | Reset |
   |---|---|---|
   | Claude 3.7 | 42% | in 2h 15m |
   | Gemini 2.5 | 18% | in 4h 50m |
   

3. Rich Markup Elements:
   • # Headings to ###### Headings
   • ==Highlighted Text== (rendered with Telegram's yellow marker)
   • ||Spoiler Text||
   • > Expandable block quotes

🛡️ Security & Authentication

• User Allowlist Enforcement: Every incoming message and callback query is checked against TELEGRAM_ALLOWED_USER_IDS. Unauthorized requests are immediately rejected.
• Timing-Safe HMAC Verification: Agent authentication tokens use crypto.timingSafeEqual to prevent timing-attack leakage.
• Path Traversal Protection: The file manager checks canonical file paths to prevent escaping the approved workspace root directory.
• Encrypted Local Storage: Sensitive state is stored locally with secure permissions (0600).

🧪 Development & Testing

Run unit and integration test suites:

# Run all tests with Vitest
pnpm test

# Run Typecheck across all 10 packages
pnpm typecheck

# Lint all packages
pnpm lint

📄 License

MIT License. Built for personal workflow automation with Google Antigravity IDE and Telegram.