mguptahub/plane-telegram repository overview

⁠Plane Telegram AI Bot

A self-hosted Docker service that connects Plane.so⁠ to Telegram via AI. Ask questions about your projects, issues, cycles, and more — right from Telegram.

Supports two deployment modes:

• Personal mode (default) — one workspace, one user, zero setup friction
• Multi-user mode — any Telegram user can /login with their own Plane credentials; ideal for shared team bots or public deployments

⁠Architecture

Telegram → Bot (python-telegram-bot) → AI (Claude/GPT) + Plane Tools → Plane.so

The AI uses Plane tools to query and interact with your workspace. It decides which tools to call based on your natural language questions. Tools are built on the official plane-sdk with lean schemas to minimise token usage, backed by an SQLite cache for workspace data.

⁠Prerequisites

1. Plane PAT (API Key) — Generate from your Plane workspace settings → API Tokens
2. Telegram Bot Token — Create a bot via @BotFather⁠ on Telegram
3. AI API Key — From Anthropic⁠ or OpenAI⁠
4. Docker — Installed on your server

⁠Setup Telegram Bot

1. Open Telegram and search for @BotFather⁠
2. Send /newbot and follow the prompts:
   • Bot name: Choose a display name (e.g., "Plane AI Assistant")
   • Bot username: Must end in "bot" (e.g., "my_plane_ai_bot")
3. BotFather will give you a bot token — save it for TELEGRAM_BOT_TOKEN

Optional extras via BotFather:

• /setdescription — Description shown in the chat header
• /setabouttext — Text shown in the bot's profile
• /setuserpic — Profile picture

⁠Quick Start

⁠Personal Mode (single user)

Run the pre-built Docker image:

docker run -d \
  --name plane-telegram \
  -v $(pwd)/data:/app/data \
  -e PLANE_PAT=your_plane_api_key \
  -e PLANE_WORKSPACE_SLUG=your-workspace-slug \
  -e TELEGRAM_BOT_TOKEN=your_telegram_bot_token \
  -e AI_PROVIDER=anthropic \
  -e AI_API_KEY=your_ai_api_key \
  --restart unless-stopped \
  mguptahub/plane-telegram:latest

That's it! Replace the values with your credentials, find your bot on Telegram, and send /start.

⁠Multi-User Mode (shared / team bot)

Add MULTI_USER=true and omit PLANE_PAT / PLANE_WORKSPACE_SLUG:

docker run -d \
  --name plane-telegram \
  -v $(pwd)/data:/app/data \
  -e MULTI_USER=true \
  -e TELEGRAM_BOT_TOKEN=your_telegram_bot_token \
  -e AI_PROVIDER=anthropic \
  -e AI_API_KEY=your_ai_api_key \
  --restart unless-stopped \
  mguptahub/plane-telegram:latest

Each user (or group chat) runs /login to connect their own Plane account. See Multi-User Mode⁠ for details.

⁠Additional Configuration (Optional)

docker run -d \
  --name plane-telegram \
  -v $(pwd)/data:/app/data \
  -e PLANE_PAT=your_plane_api_key \
  -e PLANE_WORKSPACE_SLUG=your-workspace-slug \
  -e TELEGRAM_BOT_TOKEN=your_telegram_bot_token \
  -e AI_PROVIDER=openai \
  -e AI_API_KEY=your_ai_api_key \
  -e AI_MODEL=gpt-4o \
  -e AI_BASE_URL=https://api.openai.com/v1 \
  -e MAX_HISTORY_MESSAGES=15 \
  -e SESSION_TIMEOUT_MINUTES=60 \
  -e DEBUG_LOGGING=false \
  --restart unless-stopped \
  mguptahub/plane-telegram:latest

⁠Environment Variables

⁠AI_BASE_URL Examples

⁠Available Tools

⁠Bot Commands

The bot registers all commands with Telegram automatically — they appear in the / menu.

⁠Account (multi-user mode only)

⁠General

⁠Workspace

Examples:

/workspace
/workspace my-company
/workspace show

Each chat session has its own active workspace. The default is set by PLANE_WORKSPACE_SLUG. Switching workspace rebuilds the cache and resets the active project (projects are workspace-scoped).

⁠Project Context

Set an active project once so you don't need to type the identifier on every /workitems call.

Examples:

/project
/project BACK
/project INVESTOS

The active project is cleared automatically when you switch workspace.

⁠Quick Lists

Explicit mode — project identifier always required, ignores active project context. Useful for one-off lookups across projects.

Context mode — uses the active project set by /project. Set it once, then query freely.

<PROJ> is the project identifier (e.g. BACK, INVESTOS). The optional [query] for work items is plain English — the AI resolves it into filters (state, priority, assignee, label). Only one filter value is supported per field.

Examples:

/list projects

# Explicit — project always required
/list workitems BACK
/list workitems BACK todo
/list workitems BACK high priority
/list workitems BACK assigned to me
/list workitems BACK labeled as James
/list states BACK
/list labels BACK
/list members BACK

# Context — /project BACK must be set first
/workitems
/workitems todo
/workitems in progress
/workitems urgent
/workitems assigned to me
/workitems labeled as James
/states
/labels
/members

⁠Cache Management

The bot caches workspace data (user info, projects, states, labels, members) in SQLite to reduce API calls and speed up responses.

Project states, labels, and members are lazily cached on first use and reused for subsequent calls. Use /cache clean after making structural changes in Plane (new states, members, etc.).

⁠Example Conversations

These are natural language queries you can send directly to the bot (no commands needed):

⁠General Questions

Who am I?
What workspace am I in?

⁠Projects

List all my projects
How many projects do I have?
Tell me about the Backend project

⁠Work Items

What are the open issues in project Backend?
Show me all urgent items in INVESTOS
What issues are assigned to me in BACK?
Get me issue BACK-42
What's the status of PROJ-7?

⁠Creating & Updating

Create an issue titled "Fix auth bug" with high priority in project Backend
Create a new todo in INVESTOS: "Update pricing page"
Update BACK-42 to Done
Change the priority of PROJ-7 to urgent
Assign BACK-15 to John

⁠Workspace & Members

Who are the members of the BACK project?
List all workspace members
What states does the INVESTOS project have?
What labels are available in BACK?

⁠Multi-User Mode

Set MULTI_USER=true to allow any Telegram user (or group chat) to connect their own Plane account. The bot stores credentials per-chat and isolates all data (cache, history, active workspace) between chats.

⁠Registration flow

User:  /login
Bot:   Step 1 — reply with your Plane API token
User:  plane_pat_abc123...          ← bot deletes this message for security
Bot:   ✅ Verified as John ([email protected])
       Step 2 — reply with your workspace slug
User:  my-company
Bot:   ✅ Registered! Found 5 projects in workspace my-company.

⁠Multi-user commands

⁠How it works

• Each chat gets its own credential store and cache namespace in SQLite
• PLANE_PAT and PLANE_WORKSPACE_SLUG environment variables are optional when MULTI_USER=true
• In groups, the /login flow uses Telegram's ForceReply so the bot receives replies even with privacy mode enabled
• /logout removes the registration, all conversation history, and all cache entries for that chat

⁠Per-chat workspace switching

In multi-user mode, each chat also has its own active workspace. The registered workspace is the default — users can switch with /workspace <slug> at any time. Each chat tracks its own:

• Active workspace — default is the registered workspace slug
• Active project — set with /project <IDENTIFIER>
• Cache — scoped to the chat, rebuilt on /login and /cache clean

⁠Data & Privacy

• Self-hosted: Your Plane PAT, AI keys, and conversation data never leave your infrastructure
• SQLite: Chat history and cache are stored locally in ./data/chat_history.db (volume-mapped)
• No telemetry: The bot doesn't phone home

⁠Updating

Pull the latest image and restart:

docker pull mguptahub/plane-telegram:latest
docker stop plane-telegram
docker rm plane-telegram
# Then run the docker run command from Quick Start

Your chat history and cache persist in the ./data volume.

⁠Troubleshooting

Bot not responding?

• Check logs: docker logs -f plane-telegram
• Verify your Telegram bot token is correct
• Make sure the bot is not blocked or hasn't been stopped

Plane connection fails?

• Verify your PLANE_PAT is valid and has the right permissions
• Verify your PLANE_WORKSPACE_SLUG is correct (the slug, not the full URL)
• For self-hosted: ensure PLANE_BASE_URL is reachable from inside the container
• Check logs: docker logs -f plane-telegram

AI errors?

• Verify your AI_API_KEY is valid and has credits
• Check the model name in AI_MODEL is correct for your provider

Work item filters not working?

• Run /cache clean to ensure states and members are freshly cached
• Try /cache show to inspect what's cached
• Note: each filter (state, priority, assignee, label) accepts only one value at a time

Commands not showing in Telegram?

• Send /help to force re-registration of commands
• Force-close and reopen Telegram (the commands menu is cached client-side)

⁠Development

⁠Clone and Setup

git clone https://github.com/mguptahub/plane-telegram-ai
cd plane-telegram-ai
cp .env.example .env
# Edit .env with your credentials

⁠Build and Run with Docker Compose

docker compose up -d --build

Check logs:

docker compose logs -f

⁠Debug Logging

Set DEBUG_LOGGING=true to write per-request JSON logs to data/debug_logs/. Each file captures the full AI exchange including tool calls, token usage, and cache hits.

⁠License

MIT