Bridge your local Gemini CLI session to Telegram.
Talk to your local AI agent from anywhere — with streaming replies, per-user sessions, and a live dashboard.
| Feature | Details |
|---|---|
| Per-user sessions | Each Telegram user gets an isolated Gemini session. No cross-talk. |
| Live streaming replies | Bot edits its message in real-time as Gemini thinks, like a typing effect. |
| Crash recovery | Gemini subprocess auto-respawns on crash. Sessions recover automatically. |
| Timeout handling | All RPC calls have deadlines. Hung requests fail cleanly. |
| Admin commands | Manage users entirely from Telegram: approve, revoke, promote, list. |
| File & image support | Send photos or documents — forwarded to Gemini with captions. |
| Web dashboard | Live session monitor at http://localhost:7823 with auto-refresh. |
| Busy guard | If you send a second message while one is processing, you get a clear notice. |
| Session history | /history shows your last 10 exchanges in the current session. |
- Bun (recommended) or Node.js 20+
- Gemini CLI installed and authenticated (
gemini --acpmust work) - A Telegram Bot Token from @BotFather
git clone https://github.com/yourusername/gemini-telegram-bridge.git
cd gemini-telegram-bridge
bun install
cp .env.example .env
# Edit .env and fill in TELEGRAM_BOT_TOKEN# Production
bun run start
# Development (auto-restart on file changes)
bun run dev
# Follow logs
bun run logs-
Message your bot on Telegram — any text works.
-
The bot replies with a 6-character pairing code.
-
Approve it from Telegram (if you're already an admin) using
/approve CODE. -
Or approve it from the terminal:
# Linux / macOS touch ~/.gemini/channels/telegram/approved/YOUR_CODE # Windows PowerShell New-Item "$HOME\.gemini\channels\telegram\approved\YOUR_CODE"
-
The bot confirms. You're in.
First user to be approved automatically becomes admin.
| Command | What it does |
|---|---|
/start |
Welcome message + session info |
/help |
Show all available commands |
/reset |
Start a fresh conversation with Gemini |
/status |
Bridge health, session count, uptime |
/history |
Last 10 messages in your current session |
/myid |
Show your numeric Telegram user ID |
| Command | What it does |
|---|---|
/users |
List all approved users (🟢 = online) |
/pending |
Show pending pairing requests |
/approve <code> |
Approve a pairing code without touching the terminal |
/revoke <user_id> |
Revoke a user's access immediately |
/promote <user_id> |
Grant admin rights to a user |
Open http://localhost:7823 in your browser while the bridge is running.
Shows:
- Gemini status (online/offline, with pulsing indicator)
- Active sessions with last-activity time and busy state
- All approved users and whether they're currently connected
- Pending approvals with codes ready to copy
- Rolling log tail (last 30 lines)
Auto-refreshes every 5 seconds. Change the port with DASHBOARD_PORT in .env.
| Variable | Default | Description |
|---|---|---|
TELEGRAM_BOT_TOKEN |
(required) | Token from BotFather |
GEMINI_PATH |
gemini |
Full path to gemini.cmd if not in PATH |
SESSION_TIMEOUT_MS |
3600000 |
Idle session expiry in ms (default 1h) |
STREAM_INTERVAL_MS |
700 |
How often to edit the message while streaming |
DASHBOARD_PORT |
7823 |
Port for the web dashboard |
-
Create
start-bridge.vbssomewhere permanent (e.g.,C:\Users\YourUser\scripts\):Set WshShell = CreateObject("WScript.Shell") WshShell.Run "bun run C:\path\to\gemini-telegram-bridge\bridge.ts", 0 Set WshShell = Nothing
-
Press
Win + R, typeshell:startup, press Enter. -
Place a shortcut to the
.vbsfile in that folder.
Create /etc/systemd/system/gemini-bridge.service:
[Unit]
Description=Gemini Telegram Bridge
After=network.target
[Service]
Type=simple
User=YOUR_USER
WorkingDirectory=/path/to/gemini-telegram-bridge
EnvironmentFile=/path/to/gemini-telegram-bridge/.env
ExecStart=/home/YOUR_USER/.bun/bin/bun run bridge.ts
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.targetsudo systemctl daemon-reload
sudo systemctl enable --now gemini-bridge
sudo journalctl -u gemini-bridge -f # live logsgemini-telegram-bridge/
├── bridge.ts — Bot logic, commands, message handlers
├── gemini.ts — GeminiProcess: lifecycle, RPC, streaming, crash recovery
├── access.ts — AccessManager: users, pairing codes, admin roles
├── dashboard.ts — Web dashboard (Bun HTTP server)
├── types.ts — Shared TypeScript interfaces
├── .env.example — Configuration template
└── bridge.log — Runtime log file (auto-created)
MIT