claude-link

ClaudeLink

Bidirectional Telegram messaging for Claude Code.

Website: claudelink.xyz

Overview

ClaudeLink bridges Claude Code with Telegram, enabling AI-powered messaging with clear attribution. Link your Telegram account once, and Claude can send messages and check incoming messages on your behalf.

flowchart LR
    A[Claude Code] <-->|MCP| B[ClaudeLink Server]
    B <-->|Telegram API| C[Telegram]

    style A fill:#ff6b35,stroke:#cc5500,color:#fff
    style B fill:#00d4ff,stroke:#0099cc,color:#000
    style C fill:#0088cc,stroke:#006699,color:#fff

Quick Start

Option A: Install Plugin (Recommended)

/plugin marketplace add guzus/claude-link
/plugin install claude-link

Then run /claude-link:setup to link your Telegram.

Option B: Manual Setup

1. Add MCP Server to Claude Code

claude mcp add --transport sse claudelink https://api.claudelink.xyz/mcp

2. Link Your Telegram

Just ask Claude: "Link my Telegram"

Claude will generate a link - click it to open Telegram and complete setup automatically.

Alternative (manual):

1. Message @claude_link_hermes_bot on Telegram
2. Send /link to get a 6-character code
3. In Claude Code: "Link my Telegram with code ABC123"

3. Start Using

Just ask Claude:

"Notify me on Telegram when you're done"
"Check my Telegram messages"
"Send a message to @alice saying the PR is ready"
"Run the tests and message me the results"

That's it! No local setup required.

Mobile Workflow

Reply to Claude from your phone! When Claude needs input:

1. Claude sends you a question via Telegram
2. You reply to the ClaudeLink bot with your answer
3. Claude checks messages and continues working

This lets you interact with Claude Code from anywhere without returning to your terminal.

To enable this workflow, copy the example CLAUDE.md to your project:

curl -o CLAUDE.md https://raw.githubusercontent.com/guzus/claude-link/main/examples/CLAUDE.md

This tells Claude when and how to use Telegram for remote Q&A.

---

Features

• Bidirectional Messaging - Send messages and check incoming messages
• Delegated Messaging - Claude sends messages with your username attribution
• Secure Linking - 6-character code verification connects your Telegram
• Auto-Notifications - Get notified when Claude finishes tasks (via hooks)
• Simple Stack - Bun + TypeScript + PostgreSQL + Hono

MCP Tools

Tool	Description
claude_link_send	Send a message to a Telegram user (@username or ID)
claude_link_notify_self	Send a notification to yourself
claude_link_check_messages	Check for incoming messages from Telegram
claude_link_reply	Reply to an incoming message
claude_link_ask	Ask a question via Telegram and wait for response
claude_link_status	Check if your Telegram is linked
claude_link_get_link	Generate a Telegram deep link to connect (recommended)
claude_link_link	Link with a verification code (manual method)
claude_link_unlink	Unlink your Telegram account

Plugin Commands

Command	Description
/claude-link:setup	Guided setup to link your Telegram
/claude-link:notify	Send a notification to yourself
/claude-link:ask	Ask a question via Telegram and wait for response
/claude-link:check-messages	Check for incoming Telegram messages
/claude-link:reply	Reply to an incoming message

Bot Commands (Telegram)

Command	Description
/start	Get started with ClaudeLink
/link	Generate a verification code
/unlink	Disconnect your account
/status	Check connection status

Auto-Notifications (Hooks)

Get notified automatically when Claude finishes tasks by setting your username:

# Add to ~/.bashrc or ~/.zshrc
export CLAUDE_LINK_USERNAME="your_telegram_username"

The plugin includes a Stop hook that sends a Telegram notification whenever Claude completes work.

Note: You must link your account first via /claude-link:setup.

---

Self-Hosting

Want to run your own ClaudeLink server?

Prerequisites

• Bun runtime
• PostgreSQL database
• Telegram Bot Token (from @BotFather)

Deploy to Railway

1. Fork this repository
2. Create a new Railway project
3. Add PostgreSQL database
4. Deploy the server/ directory
5. Set environment variables:

   TELEGRAM_BOT_TOKEN=your_bot_token
   DATABASE_URL=${{Postgres.DATABASE_URL}}
   

Run Locally

# Clone and setup
git clone https://github.com/guzus/claude-link.git
cd claude-link

# Start PostgreSQL
docker compose up -d postgres

# Configure environment
cp .env.example .env
# Edit .env with your TELEGRAM_BOT_TOKEN

# Run server
cd server
bun install
bun run dev