Antigravity (AGY) Telegram Bot Service
A high-performance, asynchronous Telegram Bot designed to interact seamlessly with Google Antigravity (agy CLI) directly from Telegram with Native System Authentication (Zero API Key required).
🌟 Key Features
- ⚡ Real-Time Streaming: Stream tokens, thinking/reasoning process, and tool execution status directly to Telegram with debounce rate-limit protection.
- 🔑 Native System Authentication: Uses pre-authenticated local AGY session natively without requiring external Gemini API keys.
- 🧠 Multi-Model Support: Switch effortlessly between Gemini 3.7 Flash, Gemini 3.1 Pro, Claude Sonnet 4.6, GPT-OSS 120B, and more via interactive inline menus (
/model). - 🎯 Reasoning Effort Control: Fine-tune depth on the fly with
/effort low,/effort medium, or/effort high. - 📁 Workspace Control: Dynamically bind agent workspaces to any directory on the server (
/workspace /path/to/project). - 📎 File & Document Analysis: Upload code files, images, logs, or documents directly into Telegram for instant inspection and editing.
- 🛑 Task Cancellation: Abort long-running generations or tool steps instantly with
/cancel. - 🔒 Enterprise-Grade Security: Whitelist user IDs, admin-only shell executor (
/exec), and optional PIN/Password authentication (/auth <password>). - 🔄 Systemd Service: Auto-restart on failure, launch on system boot, and manage logs via journalctl.
📁 Directory Structure
/root/telegram-agy-bot/
├── .env # Bot credentials & configuration
├── .env.example # Configuration template
├── bot.py # Main Telegram Bot application & handlers
├── agy_engine.py # Native AGY CLI async streaming engine
├── formatters.py # HTML parsing, message chunking, reasoning styling
├── config.py # Configuration management
├── manage.sh # Management utility script
├── sessions.json # Persisted user sessions & state
└── venv/ # Dedicated Python 3.12 virtual environment
🚀 Quick Setup
1. Configure Bot Token
Obtain a bot token from @BotFather on Telegram and set it:
/root/telegram-agy-bot/manage.sh set-token "YOUR_TELEGRAM_BOT_TOKEN"
2. Whitelist Telegram User ID
# Whitelist your Telegram User ID (get your ID from @userinfobot):
/root/telegram-agy-bot/manage.sh add-user 12345678
3. Start the Service
/root/telegram-agy-bot/manage.sh start
4. Check Status & Logs
/root/telegram-agy-bot/manage.sh status
/root/telegram-agy-bot/manage.sh logs
🤖 Available Bot Commands
| Command | Description |
|---|---|
/start |
Launch bot, verify access, and display interactive dashboard |
/help |
Complete command reference and usage examples |
/tasks or /schedule |
Interactive Scheduled Tasks & Cron Job Manager |
/schedule <timing> | <prompt> |
Schedule an AI prompt, shell cmd, or reminder |
/projects or /project |
Interactive Multi-Project Manager |
/newproject <name> |
Create & activate an isolated project workspace |
/switch <name> |
Switch active project |
/backup [name] |
Zip project workspace into <=50MB files and deliver to chat |
/new or /reset |
Start a clean, fresh conversation session |
/lastconv or /resume |
Reopen and resume the last or previous conversation |
/conversations or /convs |
Interactive conversation history browser & switcher |
/usage or /quota |
Check real-time AGY usage, 5h & 7d quotas |
/model |
Interactive inline keyboard to select active AI model |
/lang [code|name] |
Set agent response language (Persian, English, etc.) |
/effort [low|med|high] |
Configure reasoning depth and effort |
/workspace [path] |
View or change the working directory on the server |
/status |
View system status, active conversation, model, disk space |
/server or /hardware |
Real-time RAM, CPU, Swap, Disk storage, and Uptime monitor |
/cancel |
Cancel any active generation or agent execution |
/invite [user_id] |
(Admin only) Invite user or create invite link |
/users or /whitelist |
(Admin only) Manage authorized users & invitations |
/uninvite <user_id> |
(Admin only) Revoke user authorization |
/invitelink |
(Admin only) Generate new single-use or multi-use invite link |
/auth <pass> |
Authenticate dynamically with PIN password |
/exec <cmd> |
(Admin only) Run shell commands on the server |
⚙️ Service Management
You can manage the bot service using either systemctl or ./manage.sh:
# Using systemctl:
systemctl start agy-telegram-bot
systemctl stop agy-telegram-bot
systemctl restart agy-telegram-bot
systemctl status agy-telegram-bot
journalctl -u agy-telegram-bot -f
# Using helper script:
/root/telegram-agy-bot/manage.sh start
/root/telegram-agy-bot/manage.sh restart
/root/telegram-agy-bot/manage.sh logs