Gemini Telegram Bot

A Telegram bot that gives you remote agentic access to Google's Gemini CLI. Chat naturally with Gemini about your code from anywhere — no terminal required.

• Conversational — ask Gemini to analyse, edit, or explain your code in plain language
• Session persistence — per user + project, auto-resume on the next message
• Event-driven — webhooks and cron jobs can invoke the agent proactively
• Self-hosted — single process, SQLite, systemd-friendly

Demo

You:  Can you help me add error handling to src/api.py?
Bot:  I'll analyse src/api.py and add error handling...
      [Gemini reads the file, suggests improvements, applies the change]

You:  Looks good. Run the tests.
Bot:  Running pytest...
      All 47 tests passed.

Quick start

1. Prerequisites

• Python 3.11+
• Gemini CLI — npm install -g @google/gemini-cli, then either gemini auth login (OAuth) or set GEMINI_API_KEY
• Telegram Bot Token from @BotFather

2. Install

git clone https://github.com/aralozaltin/gemini-telegram-bot.git
cd gemini-telegram-bot
make dev    # requires Poetry

3. Configure

cp .env.example .env
# edit .env

Minimum:

TELEGRAM_BOT_TOKEN=1234567890:ABC-DEF...
TELEGRAM_BOT_USERNAME=my_gemini_bot
APPROVED_DIRECTORY=/home/you/workspace
ALLOWED_USERS=123456789       # your Telegram user ID

4. Run

make run          # production
make run-debug    # with debug logging

Then message your bot on Telegram.

Authentication options

OAuth (recommended, free quota):

gemini auth login    # opens a browser, caches creds in ~/.gemini/

On a headless server, run gemini auth login on your local machine, then scp ~/.gemini/oauth_creds.json, ~/.gemini/google_accounts.json, ~/.gemini/settings.json to the server.

API key:

# .env
GEMINI_API_KEY=your-key-from-aistudio.google.com/apikey

Modes

Agentic (default)

Just talk. The bot routes every message to Gemini with project context, streams back tool calls and reasoning, and auto-resumes the session on the next turn.

Commands: /start  /new  /status  /verbose  /repo
          /sync_threads   (only if ENABLE_PROJECT_THREADS=true)

/verbose 0|1|2 controls how much of Gemini's work is streamed live.

Classic (AGENTIC_MODE=false)

Terminal-like interface with inline keyboards, directory navigation, quick actions, git integration, session export.

Commands: /start /help /new /continue /end /status /cd /ls /pwd
          /projects /export /actions /git

Event-driven automation

• Webhooks (ENABLE_API_SERVER=true) — receive GitHub or generic events via HMAC-SHA256 / Bearer auth, route through Gemini
• Scheduler (ENABLE_SCHEDULER=true) — APScheduler cron jobs that invoke the agent
• Notifications — route agent responses to configured chats

See docs/setup.md and docs/configuration.md.

Configuration (highlights)

# Gemini
GEMINI_API_KEY=...                  # optional if OAuth is set
GEMINI_MODEL=gemini-2.5-pro         # or leave empty for auto routing
GEMINI_TIMEOUT_SECONDS=300
GEMINI_CLI_PATH=/path/to/gemini     # optional, auto-detected via PATH

# Mode + output
AGENTIC_MODE=true
VERBOSE_LEVEL=1                     # 0 quiet / 1 normal / 2 detailed

# Rate limiting
RATE_LIMIT_REQUESTS=10
RATE_LIMIT_WINDOW=60

# Agentic platform
ENABLE_API_SERVER=false
ENABLE_SCHEDULER=false
NOTIFICATION_CHAT_IDS=123,456

Full reference: docs/configuration.md and .env.example.

Security

Defence in depth:

• Whitelist-based user authentication
• Directory sandboxing (APPROVED_DIRECTORY + path traversal prevention)
• Rate limiting per user
• Input validation (dangerous patterns blocked)
• Audit logging of every action

See SECURITY.md.

Development

make dev           # install everything
make test          # pytest + coverage
make lint          # black + isort + flake8 + mypy
make format        # auto-format
make run-debug     # debug logging
make run-watch     # auto-restart on source changes

See GEMINI.md for architecture and how to add commands.

Gemini-specific notes

• No cost (total_cost_usd) is emitted by Gemini CLI; the /status command shows cost as 0.0. Token counts are tracked.
• Multimodal input via gemini -p is not supported; attached images/PDFs are currently dropped by the agent wrapper (Telegram upload still works, file paths are kept in storage).
• OAuth's free tier gives access to gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite, and gemini-3-flash-preview. gemini-3-pro currently returns ModelNotFoundError on OAuth — likely paid-tier only.

Acknowledgements

Fork of RichardAtCT/claude-code-telegram — the Telegram and platform layers come straight from Richard's work; the agent integration was rewritten for Gemini CLI. MIT license preserved with upstream copyright in LICENSE.

• Gemini CLI — Google
• python-telegram-bot

License

MIT — see LICENSE.