Skip to content
BranchesTags

Repository files navigation

Telegram Droid Connector

Telegram bot bridge for Factory AI Droid CLI — Control your AI coding agent directly from Telegram.

Python Telegram Bot Factory Droid

Telegram Droid Connector is a Telegram bot that bridges Factory AI's Droid (an AI coding agent) with Telegram, allowing you to interact with your AI-powered software engineering assistant from anywhere. Send messages, review code, manage MCP servers, and get real-time tool progress — all through your Telegram chat.

Features

  • Chat with Droid from Telegram — Send natural language messages and receive AI responses directly in your Telegram chat
  • Real-time tool progress — See which tools Droid is using (file reads, grep searches, command executions) as brief progress updates
  • Permission approval via inline buttons — When Droid requests permission to use a tool, approve or deny with one tap
  • Interactive questionnaires — When Droid asks questions, answer them via inline keyboard buttons or free text
  • Conversation context persistence — Chat history is saved locally and restored when sessions restart, so Droid remembers previous conversations
  • MCP server management — Add, remove, toggle, and browse MCP (Model Context Protocol) servers and tools directly from Telegram
  • One-shot commands — Run code reviews and readiness reports without starting a persistent session
  • Multi-user authorization — Restrict bot access to specific Telegram user IDs
  • Autonomy level control — Set Droid's autonomy (low/medium/high) per session
  • Auto-startup on Windows — Included scripts for running the bot as a Windows startup task

How It Works

Telegram User  →  Telegram Bot  →  Droid SDK Client  →  Factory AI Droid CLI
                     ↑                                    ↓
              Inline Buttons / Text              Tool Progress / Responses

The bot uses the Droid SDK (droid-sdk Python package) to communicate with the Factory AI Droid CLI process. Each Telegram chat gets its own Droid session, with full support for tool permission requests and interactive questionnaires via Telegram's inline keyboard system.

Prerequisites

Installation

1. Clone the repository

git clone https://github.com/MaulanaR/telegram-droid-connector.git
cd telegram-droid-connector

2. Install Python dependencies

pip install -r requirements.txt

This installs:

  • python-telegram-bot — Telegram Bot API wrapper
  • python-dotenv — Environment variable loader
  • droid-sdk — Factory AI Droid SDK client

3. Configure environment variables

Copy the example env file and fill in your credentials:

cp .env.example .env

Edit .env with your values:

# Required: Telegram Bot Token from @BotFather
TELEGRAM_BOT_TOKEN=your_bot_token_here

# Required: Factory AI API Key
FACTORY_API_KEY=fk-your-key-here

# Required: Your Telegram user ID (comma-separated for multiple users)
# Find your ID by messaging @userinfobot on Telegram
ALLOWED_USER_IDS=123456789

# Optional: Droid autonomy level (low, medium, high)
DEFAULT_AUTO_LEVEL=medium

# Optional: AI model ID (empty = default model)
DEFAULT_MODEL=

# Optional: Working directory for Droid sessions
DEFAULT_CWD=.

# Optional: Execution timeout in seconds
EXEC_TIMEOUT=300

4. Run the bot

python main.py

You should see: Bot starting... in the console.

5. Test it on Telegram

Open your bot on Telegram and send /start to see the available commands.

Usage

Commands

Command Description
/start Show help and available commands
/help Show help and available commands
/new Start a new Droid session
/stop Stop the current active session
/interrupt Interrupt a running Droid session
/clear Clear saved conversation context (fresh start)
/status Show current session info (ID, autonomy, model, CWD)
/auto <level> Set autonomy level: low, medium, or high
/model <id> Set the AI model for Droid
/cwd <path> Set the working directory for Droid
/skills List available Droid skills
/mcp List configured MCP servers
/mcp_tools List available MCP tools
/mcp_registry Browse the MCP server registry
/mcp_add <name> <url> Add a new MCP server
/mcp_remove <name> Remove an MCP server
/review Run a code review (one-shot)
/readiness Generate a readiness report (one-shot)

Chatting with Droid

Simply send any text message to the bot (not a command) and Droid will process it. You'll see:

  1. A progress message showing what tool Droid is currently using (e.g., "⏳ Read File: src/main.py")
  2. The final response when Droid completes its turn

Permission Requests

When Droid wants to use a tool that requires approval, you'll get an inline message with Allow ✅ and Deny ❌ buttons. Tap one to respond.

You can also reply with text: allow, yes, ya, ok, or y to approve, or anything else to deny.

Interactive Questions

When Droid asks you a question (via the AskUser tool), you'll see inline keyboard buttons with the options. Tap to select your answer, or type a free-text response if no options are shown.

Context Persistence

Conversation history is automatically saved per chat. When you restart the bot or start a new session, previous context is loaded so Droid remembers what you discussed. Use /clear to wipe saved context.

Windows Auto-Startup

To run the bot automatically when you log in to Windows:

# Install as startup task
install_startup.bat

# Remove startup task
uninstall_startup.bat

# Stop the running bot
stop_bot.bat

To start manually in the background: double-click start_background.vbs

Project Structure

telegram-droid-connector/
├── main.py              # Telegram bot handlers and command routing
├── droid_executor.py    # Droid SDK session management and context store
├── config.py            # Configuration from environment variables
├── requirements.txt     # Python dependencies
├── .env.example         # Environment variable template
├── .gitignore           # Git ignore rules
├── CLAUDE.md            # AI agent instructions (customize as needed)
├── install_startup.bat  # Windows startup task installer
├── start_background.vbs # Background launcher for Windows
├── stop_bot.bat         # Script to stop the running bot
├── uninstall_startup.bat # Windows startup task remover
└── context_store/       # Conversation history (auto-created, not committed)

Configuration Options

All configuration is via environment variables (loaded from .env):

Variable Default Description
TELEGRAM_BOT_TOKEN (required) Bot token from @BotFather
FACTORY_API_KEY (required) Factory AI API key
ALLOWED_USER_IDS (empty = all) Comma-separated Telegram user IDs allowed to use the bot
DEFAULT_AUTO_LEVEL medium Default Droid autonomy level
DEFAULT_MODEL (empty) Default AI model ID
DEFAULT_CWD . Default working directory
EXEC_TIMEOUT 300 Execution timeout in seconds
DROID_EXEC_PATH droid Path to Droid CLI executable
LOG_FILE droidtele.log Log file path
LOG_MAX_BYTES 5242880 Max log file size before rotation (5 MB)
LOG_BACKUP_COUNT 3 Number of rotated log backups
CONTEXT_DIR context_store Directory for conversation context files
MAX_CONTEXT_EXCHANGES 20 Max conversation exchanges per chat
SUMMARY_INTERVAL 5 Exchanges before context compaction

Troubleshooting

  • Bot not responding: Check that TELEGRAM_BOT_TOKEN and FACTORY_API_KEY are set correctly in .env
  • "Droid tidak merespon" timeout: Increase EXEC_TIMEOUT in .env (default 300 seconds)
  • "Anda tidak diizinkan": Add your Telegram user ID to ALLOWED_USER_IDS in .env
  • Droid CLI not found: Ensure droid is installed and available in PATH, or set DROID_EXEC_PATH to its full path
  • Session errors: Use /stop to end the current session, then /new to start fresh

Security Notes

  • Restrict bot access by setting ALLOWED_USER_IDS to only your Telegram user ID(s)
  • The bot runs Droid with the autonomy level you configure — low requires approval for most tool uses, high allows autonomous execution

License

MIT License — see LICENSE for details.

Links

Keywords: telegram bot, AI coding agent, factory droid, droid SDK, telegram AI assistant, code review bot, MCP protocol, AI agent bridge, telegram droid connector, software engineering AI, coding assistant telegram, droid CLI telegram

About

A Telegram bot interface for Factory's Droid CLI so you can chat with Droid via Telegram with knowledge histories

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages