Skip to content

README.md

Latest commit

 

History

History
279 lines (203 loc) · 9.17 KB

README.md

File metadata and controls

279 lines (203 loc) · 9.17 KB

C3Poh — Telegram Bridge for Claude Code

Python License Claude Code

"I am fluent in over six million forms of communication." C-3PO handled comms for the Rebellion. C3Poh handles comms for your Claude Code agent.

C3Poh lets you DM your Claude Code agent via Telegram and get answers back — from anywhere, on any device.

You're on your phone. You think of something. You message your agent. Claude Code handles it and replies. That's it.

Zero external dependencies. Allowlist-based access control baked in. Takes 5 minutes to set up.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Your Machine                             │
│                                                                  │
│  ┌──────────────┐      ┌──────────────┐      ┌──────────────┐  │
│  │              │      │              │      │              │  │
│  │   C3Poh      │◄────►│ Claude Code  │      │   TinMan     │  │
│  │   (bot)      │      │   (claude)   │      │  (scheduler) │  │
│  │              │      │              │      │              │  │
│  └──────┬───────┘      └──────────────┘      └──────┬───────┘  │
│         │                                           │          │
│         │ ◄─────────── HTTP notify ─────────────────┘          │
│         │              (localhost:7734)                        │
└─────────┼──────────────────────────────────────────────────────┘
          │
          │ Long-polling (outbound only)
          ▼
┌─────────────────────┐
│   Telegram API      │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│   Your Phone        │
│   (Telegram app)    │
└─────────────────────┘

No inbound ports. No webhooks. No ngrok. C3Poh polls Telegram's API for messages and uses localhost for TinMan notifications.

Part of the Claude Code Toolkit

C3Poh is the voice — it handles communication. Pair it with:

Tool Role Link
TinMan The heart — scheduled health checks tinman_for_claudecode
Heartbeat Templates The playbooks — ready-to-use checklists heartbeat-templates
Agent Blueprints The brains — starter agent templates agent-blueprints

The full stack:

[TinMan] ──heartbeat──► [Claude Code] ──notify──► [C3Poh] ──message──► [Your Phone]
                              ▲                                              │
                              └──────────────── your reply ──────────────────┘

Install

One-liner:

curl -fsSL https://raw.githubusercontent.com/andyuninvited/c3poh_for_claudecode/main/install.sh | bash

Or pip:

pip install c3poh-for-claudecode

Requirements:

  • Python 3.9+
  • Claude Code (claude CLI in your PATH)
  • A Telegram bot token (from @BotFather — free, takes 30 seconds)

Quick start

Step 1: Get a bot token

  1. Open Telegram → search @BotFather
  2. Send /newbot and follow prompts
  3. Copy the token (looks like 123456789:ABCdefGHI...)

Step 2: Find your Telegram user ID

Message @userinfobot on Telegram. It replies with your numeric user ID.

Step 3: Run setup

c3poh init

Interactive prompts walk you through token, DM policy, and allowlist.

Step 4: Start

TELEGRAM_BOT_TOKEN=your_token_here c3poh start

Now DM your bot on Telegram. Claude Code replies.

Commands

c3poh init                          Interactive first-time setup
c3poh start                         Start the bot
c3poh test                          Verify Telegram connection
c3poh test --send-to 123456789      Send a test message to yourself
c3poh status                        Show config and connection status

DM policies (access control)

Don't skip this. OpenClaw users get burned by leaving this on open.

Policy Who can DM Use when
allowlist Only your Telegram user IDs default — recommended always
pairing First person to /start becomes owner Single-user, no ID lookup
open Anyone with your bot link Demos only, never production
disabled Nobody Notify-only mode (outbound only)

Set via config or env var:

# Allowlist (recommended)
C3POH_ALLOW_FROM=123456789,987654321 c3poh start

# Pairing (first-user-wins)
C3POH_DM_POLICY=pairing c3poh start

Configuration

C3Poh looks for config at ./c3poh.json then ~/.c3poh/config.json.

{
  "dm_policy": "allowlist",
  "allow_from": ["123456789"],
  "require_mention": true,
  "notify_port": 7734,
  "notify_host": "127.0.0.1",
  "claude_timeout_seconds": 300,
  "log_messages": true
}

Token is never saved to disk — always set via env var:

export TELEGRAM_BOT_TOKEN=your_token_here

Environment variable overrides:

TELEGRAM_BOT_TOKEN=...          # required
C3POH_ALLOW_FROM=111,222        # comma-separated Telegram user IDs
C3POH_DM_POLICY=allowlist
C3POH_NOTIFY_PORT=7734
C3POH_CLAUDE_TIMEOUT=300

TinMan integration

Pair C3Poh with TinMan to get heartbeat alerts on your phone:

In TinMan's config (tinman.json):

{
  "notify_c3poh": true,
  "c3poh_endpoint": "http://localhost:7734/notify"
}

Now when TinMan detects something (disk space low, failing tests, stale branches), it sends the alert to C3Poh → you get a Telegram message.

Security notes

What C3Poh protects:

  • All traffic goes Telegram API → your machine (outbound only)
  • notify_host defaults to 127.0.0.1 — the notify server is never public
  • Bot token is never written to disk
  • Blocked user IDs are logged

What C3Poh does not do:

  • Store your messages anywhere except a local log (opt-out: "log_messages": false)
  • Use webhooks (long-polling only — no inbound ports needed)
  • Require any cloud account beyond Telegram

What you should do:

  • Use dm_policy: allowlist with your user ID
  • Keep your bot token in an env var or password manager, not in a file
  • Don't share your bot link publicly if you care about who can use it

How it works

You (Telegram) → Telegram API → C3Poh (long-polling)
                                    ↓
                             access check (allowlist)
                                    ↓
                            claude --print "your message"
                                    ↓
                             Claude Code response
                                    ↓
                        Telegram API → You (Telegram)

Long-polling (not webhooks): C3Poh calls Telegram's API every few seconds to check for new messages. No inbound ports, no reverse proxy, no ngrok. Runs from anywhere.

Run tests

pip install c3poh-for-claudecode[dev]
pytest tests/ -v

Roadmap

  • v0.2: Slack support
  • v0.2: Discord support
  • v0.2: Message history context (multi-turn conversations)
  • v0.3: /status and /help bot commands
  • v0.3: File/image send support
  • v1.0: Webhook mode (for production deployments)

Related

License

GNU GPLv3 — copy-left, and let's evolve together.

See LICENSE for the full text.

Built by @andyuninvited. Star if you've ever wished you could text your agent.