Takopi Setup Guide

Takopi is a Telegram bridge that allows you to interact with Claude Code via Telegram.

Related: Quartz | Cloudflare | Secrets

Installation

# Install via uv (recommended)
uv tool install takopi
 
# Or via pipx
pipx install takopi

Configuration

Create config file at ~/.takopi/takopi.toml:

default_engine = "claude"
default_project = "default-workspace"
transport = "telegram"
watch_config = true
 
[transports.telegram]
bot_token = "YOUR_BOT_TOKEN"        # From @BotFather
chat_id = -YOUR_CHAT_ID             # Your group/chat ID
session_mode = "chat"               # Maintains conversation context
show_resume_line = false
 
# Who can send messages
allowed_user_ids = [
    USER_ID_1,
    USER_ID_2,
]
 
[transports.telegram.files]
enabled = true
auto_put = true
auto_put_mode = "upload"
uploads_dir = "incoming"
allowed_user_ids = [
    USER_ID_1,
    USER_ID_2,
]
deny_globs = [
    ".git/**",
    ".env",
    ".envrc",
    "**/*.pem",
    "**/.ssh/**",
]
 
[projects.default-workspace]
path = "/home/ubuntu/claude-workspace"
worktrees_dir = ".worktrees"
default_engine = "claude"
worktree_base = "main"
 
[claude]
dangerously_skip_permissions = true
allowed_tools = [
    "Bash",
    "Read",
    "Edit",
    "Write",
    "mcp__obsidian__*",
]

Getting Telegram Credentials

Bot Token

1. Open Telegram, find @BotFather
2. Send /newbot
3. Follow instructions, get token like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Chat ID

1. Add bot to your group/chat
2. Send a message in the chat
3. Open: https://api.telegram.org/bot<TOKEN>/getUpdates
4. Find "chat":{"id":-123456789} - that’s your chat_id

User IDs

1. Message @userinfobot on Telegram
2. It will reply with your user ID

Running Takopi

Start

~/start-takopi.sh &

The script runs takopi with auto-restart on crash and logs to ~/takopi.log.

Stop

~/stop-takopi.sh

Check Logs

tail -f ~/takopi.log

Claude Code Configuration

Takopi requires Claude Code to be installed and configured:

# Install Claude Code
npm install -g @anthropic-ai/claude-code
 
# Login
claude login

MCP Servers (Optional)

Add to ~/.claude.json for Obsidian integration:

{
  "mcpServers": {
    "obsidian": {
      "type": "stdio",
      "command": "npx",
      "args": ["@mauricio.wolff/mcp-obsidian@latest", "/path/to/vault"]
    }
  }
}

Commands

See Takopi Commands for full documentation of bot commands (/publish, /restart, /health).

Commands are implemented as the takopi-plugins package. Source: /home/ubuntu/takopi-plugins/takopi_plugins/

Troubleshooting

Bot not responding

• Check bot token is correct
• Ensure bot is added to chat
• Check allowed_user_ids includes your ID

Permission errors

• Check Claude Code is logged in: claude login
• Verify allowed_tools in config

Session issues

• Delete ~/.takopi/telegram_chat_sessions_state.json to reset sessions