114 lines
5.0 KiB
Markdown
114 lines
5.0 KiB
Markdown
# 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
|
|
|
|
```text
|
|
/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](https://t.me/BotFather) on Telegram and set it:
|
|
```bash
|
|
/root/telegram-agy-bot/manage.sh set-token "YOUR_TELEGRAM_BOT_TOKEN"
|
|
```
|
|
|
|
### 2. Whitelist Telegram User ID
|
|
```bash
|
|
# Whitelist your Telegram User ID (get your ID from @userinfobot):
|
|
/root/telegram-agy-bot/manage.sh add-user 12345678
|
|
```
|
|
|
|
### 3. Start the Service
|
|
```bash
|
|
/root/telegram-agy-bot/manage.sh start
|
|
```
|
|
|
|
### 4. Check Status & Logs
|
|
```bash
|
|
/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`:
|
|
|
|
```bash
|
|
# 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
|
|
```
|