tg-claude

Control Claude Code remotely via Telegram or Discord with your Claude subscription.

Demo Video

How It Works

flowchart LR
    subgraph Clients[" "]
        TG[Telegram]
        DC[Discord]
        Hub[Claude Hub]
    end

    subgraph Core[" "]
        Bot[tg-claude]
        SDK[SDK Executor]
    end

    subgraph Harness[" "]
        MCP[MCP Servers]
        Skills[Skills]
        Plugins[Plugins]
    end

    subgraph APIs[" "]
        Claude[Claude API]
        GLM[GLM API]
        OR[OpenRouter]
    end

    subgraph Storage[" "]
        WS[Workspace]
        GH[GitHub]
    end

    TG & DC & Hub --> Bot
    Bot --> SDK
    SDK --> MCP & Skills & Plugins
    SDK --> Claude & GLM & OR
    SDK <--> WS
    WS <--> GH

    style TG fill:#0088cc,color:#fff
    style DC fill:#5865F2,color:#fff
    style Hub fill:#D97706,color:#fff
    style Bot fill:#FB8C00,color:#fff
    style SDK fill:#1976D2,color:#fff
    style MCP fill:#7C3AED,color:#fff
    style Skills fill:#7C3AED,color:#fff
    style Plugins fill:#7C3AED,color:#fff
    style Claude fill:#D4A574,color:#000
    style GLM fill:#10B981,color:#fff
    style OR fill:#6366F1,color:#fff
    style WS fill:#059669,color:#fff
    style GH fill:#333,color:#fff

Loading

Authentication

Set ONE of:

• CLAUDE_CODE_OAUTH_TOKEN - Uses your Claude subscription (run claude setup-token to get it)
• ANTHROPIC_API_KEY - Uses API key billing from Anthropic Console

Important: Do NOT set both. If ANTHROPIC_API_KEY is set alongside OAuth token, it may cause billing conflicts.

Quick Start

📖 Full Deployment Guide - Complete step-by-step tutorial

📖 Discord Integration Guide - Set up the Discord client

Deploy on Railway (Easiest)

💰 Cost: Anthropic API credits or Claude subscription + Railway hosting (~$5/mo)

1. Click the button above
2. Set required environment variables:
   • TELEGRAM_BOT_TOKEN - from @BotFather
   • TELEGRAM_ALLOWED_USER_IDS - your Telegram ID (get from @userinfobot)
   • CLAUDE_CODE_OAUTH_TOKEN - from claude setup-token (uses your Claude subscription)
   • Or ANTHROPIC_API_KEY - from Anthropic Console (uses API billing)
3. Deploy!

Deploy on VPS (Docker Compose)

git clone https://github.com/guzus/tg-claude.git
cd tg-claude
cp .env.example .env  # Edit with your tokens
docker compose up -d

Data is stored in ./persistent/ on your host (and is gitignored).

Commands

Command	Description
/ralph <task>	Autonomous loop mode (via ralph-loop Claude plugin)
/repo	Manage repositories (clone/new/list/switch)
/scan	Scan for existing repositories
/remote	Manage git remote (show/set/test)
/bot	Manage bots via Mothership (in development)
/status	Check active tasks
/cancel <id>	Cancel a running task
/limits	Check your rate limits
/config	User configuration
/ai	Toggle AI provider (Claude/GLM/OpenRouter)
/mcp	Manage MCP servers per repository
/plugin	Manage Claude plugins (including ralph-loop)
/help	Show help

Just send a plain text message to execute tasks with Claude.

Note: /bot (Mothership) commands are optional and require the Mothership CLI + Nomad. If you don't need bot deployment, you can ignore them.

Configuration

Using GLM Instead of Claude

You can use GLM-4 as an alternative AI provider:

/config set aiProvider.provider glm
/config set aiProvider.glmApiKey YOUR_ZAI_API_KEY

Get your API key from Z.ai. See the Deployment Guide for details.

Using OpenRouter

OpenRouter provides access to 100+ models from multiple providers through a unified API:

/config set aiProvider.provider openrouter
/config set aiProvider.openrouterApiKey YOUR_OPENROUTER_API_KEY

Tip: use /ai and tap Set OpenRouter Key to paste your key interactively.

Get your API key from OpenRouter.

Custom Models: By default, OpenRouter uses Minimax for all model slots. You can customize each slot independently:

/config set aiProvider.haikuModel openai/gpt-5.2
/config set aiProvider.sonnetModel anthropic/claude-sonnet-4.5
/config set aiProvider.opusModel anthropic/claude-opus-4.5

Browse available models at OpenRouter Models.

Quick Switch: Use /ai to toggle between Claude, GLM, and OpenRouter with inline buttons.

Other Settings

# Tech stack preferences
/config techstack typescript bun    # bun, npm, pnpm, yarn
/config techstack python uv         # uv, pip, poetry, pipenv

# MCP servers (per repository)
/mcp add <name> <command> [args...]
/mcp list

# CLAUDE.md template
/config claudemd show

Development

bun install
bun dev

Build Locally

docker compose build
docker compose up -d

Security

• User whitelist via TELEGRAM_ALLOWED_USER_IDS
• Rate limiting per user
• Uses --dangerously-skip-permissions - run only with trusted users

---

MIT License