{
  "markdown": "# C3Poh — Telegram Bridge for Claude Code\n\n[![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://python.org)\n[![License](https://img.shields.io/badge/License-GPLv3-green.svg)](LICENSE)\n[![Claude Code](https://img.shields.io/badge/Built%20for-Claude%20Code-orange.svg)](https://claude.ai/code)\n\n> *\"I am fluent in over six million forms of communication.\"*\n> C-3PO handled comms for the Rebellion. C3Poh handles comms for your Claude Code agent.\n\n**C3Poh** lets you DM your Claude Code agent via Telegram and get answers back — from anywhere, on any device.\n\nYou're on your phone. You think of something. You message your agent. Claude Code handles it and replies. That's it.\n\nZero external dependencies. Allowlist-based access control baked in. Takes 5 minutes to set up.\n\n<!-- TODO: Add screenshot of Telegram conversation with C3Poh -->\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                         Your Machine                             │\n│                                                                  │\n│  ┌──────────────┐      ┌──────────────┐      ┌──────────────┐  │\n│  │              │      │              │      │              │  │\n│  │   C3Poh      │◄────►│ Claude Code  │      │   TinMan     │  │\n│  │   (bot)      │      │   (claude)   │      │  (scheduler) │  │\n│  │              │      │              │      │              │  │\n│  └──────┬───────┘      └──────────────┘      └──────┬───────┘  │\n│         │                                           │          │\n│         │ ◄─────────── HTTP notify ─────────────────┘          │\n│         │              (localhost:7734)                        │\n└─────────┼──────────────────────────────────────────────────────┘\n          │\n          │ Long-polling (outbound only)\n          ▼\n┌─────────────────────┐\n│   Telegram API      │\n└─────────┬───────────┘\n          │\n          ▼\n┌─────────────────────┐\n│   Your Phone        │\n│   (Telegram app)    │\n└─────────────────────┘\n```\n\n**No inbound ports. No webhooks. No ngrok.** C3Poh polls Telegram's API for messages and uses localhost for TinMan notifications.\n\n---\n\n## Part of the Claude Code Toolkit\n\nC3Poh is the **voice** — it handles communication. Pair it with:\n\n| Tool | Role | Link |\n|------|------|------|\n| **TinMan** | The heart — scheduled health checks | [tinman_for_claudecode](https://github.com/andyuninvited/tinman_for_claudecode) |\n| **Heartbeat Templates** | The playbooks — ready-to-use checklists | [heartbeat-templates](https://github.com/andyuninvited/heartbeat-templates) |\n| **Agent Blueprints** | The brains — starter agent templates | [agent-blueprints](https://github.com/andyuninvited/agent-blueprints) |\n\n**The full stack:**\n```\n[TinMan] ──heartbeat──► [Claude Code] ──notify──► [C3Poh] ──message──► [Your Phone]\n                              ▲                                              │\n                              └──────────────── your reply ──────────────────┘\n```\n\n---\n\n## Install\n\n**One-liner:**\n```bash\ncurl -fsSL https://raw.githubusercontent.com/andyuninvited/c3poh_for_claudecode/main/install.sh | bash\n```\n\n**Or pip:**\n```bash\npip install c3poh-for-claudecode\n```\n\n**Requirements:**\n- Python 3.9+\n- [Claude Code](https://claude.ai/code) (`claude` CLI in your PATH)\n- A Telegram bot token (from [@BotFather](https://t.me/botfather) — free, takes 30 seconds)\n\n---\n\n## Quick start\n\n**Step 1: Get a bot token**\n\n1. Open Telegram → search [@BotFather](https://t.me/botfather)\n2. Send `/newbot` and follow prompts\n3. Copy the token (looks like `123456789:ABCdefGHI...`)\n\n**Step 2: Find your Telegram user ID**\n\nMessage [@userinfobot](https://t.me/userinfobot) on Telegram. It replies with your numeric user ID.\n\n**Step 3: Run setup**\n\n```bash\nc3poh init\n```\n\nInteractive prompts walk you through token, DM policy, and allowlist.\n\n**Step 4: Start**\n\n```bash\nTELEGRAM_BOT_TOKEN=your_token_here c3poh start\n```\n\nNow DM your bot on Telegram. Claude Code replies.\n\n---\n\n## Commands\n\n```\nc3poh init                          Interactive first-time setup\nc3poh start                         Start the bot\nc3poh test                          Verify Telegram connection\nc3poh test --send-to 123456789      Send a test message to yourself\nc3poh status                        Show config and connection status\n```\n\n---\n\n## DM policies (access control)\n\n**Don't skip this.** OpenClaw users get burned by leaving this on `open`.\n\n| Policy | Who can DM | Use when |\n|--------|-----------|----------|\n| `allowlist` | Only your Telegram user IDs | **default — recommended always** |\n| `pairing` | First person to /start becomes owner | Single-user, no ID lookup |\n| `open` | Anyone with your bot link | Demos only, never production |\n| `disabled` | Nobody | Notify-only mode (outbound only) |\n\nSet via config or env var:\n```bash\n# Allowlist (recommended)\nC3POH_ALLOW_FROM=123456789,987654321 c3poh start\n\n# Pairing (first-user-wins)\nC3POH_DM_POLICY=pairing c3poh start\n```\n\n---\n\n## Configuration\n\nC3Poh looks for config at `./c3poh.json` then `~/.c3poh/config.json`.\n\n```json\n{\n  \"dm_policy\": \"allowlist\",\n  \"allow_from\": [\"123456789\"],\n  \"require_mention\": true,\n  \"notify_port\": 7734,\n  \"notify_host\": \"127.0.0.1\",\n  \"claude_timeout_seconds\": 300,\n  \"log_messages\": true\n}\n```\n\n**Token is never saved to disk** — always set via env var:\n```bash\nexport TELEGRAM_BOT_TOKEN=your_token_here\n```\n\n**Environment variable overrides:**\n```bash\nTELEGRAM_BOT_TOKEN=...          # required\nC3POH_ALLOW_FROM=111,222        # comma-separated Telegram user IDs\nC3POH_DM_POLICY=allowlist\nC3POH_NOTIFY_PORT=7734\nC3POH_CLAUDE_TIMEOUT=300\n```\n\n---\n\n## TinMan integration\n\nPair C3Poh with [TinMan](https://github.com/andyuninvited/tinman_for_claudecode) to get heartbeat alerts on your phone:\n\n**In TinMan's config (`tinman.json`):**\n```json\n{\n  \"notify_c3poh\": true,\n  \"c3poh_endpoint\": \"http://localhost:7734/notify\"\n}\n```\n\nNow when TinMan detects something (disk space low, failing tests, stale branches), it sends the alert to C3Poh → you get a Telegram message.\n\n---\n\n## Security notes\n\n**What C3Poh protects:**\n- All traffic goes Telegram API → your machine (outbound only)\n- `notify_host` defaults to `127.0.0.1` — the notify server is never public\n- Bot token is never written to disk\n- Blocked user IDs are logged\n\n**What C3Poh does not do:**\n- Store your messages anywhere except a local log (opt-out: `\"log_messages\": false`)\n- Use webhooks (long-polling only — no inbound ports needed)\n- Require any cloud account beyond Telegram\n\n**What you should do:**\n- Use `dm_policy: allowlist` with your user ID\n- Keep your bot token in an env var or password manager, not in a file\n- Don't share your bot link publicly if you care about who can use it\n\n---\n\n## How it works\n\n```\nYou (Telegram) → Telegram API → C3Poh (long-polling)\n                                    ↓\n                             access check (allowlist)\n                                    ↓\n                            claude --print \"your message\"\n                                    ↓\n                             Claude Code response\n                                    ↓\n                        Telegram API → You (Telegram)\n```\n\nLong-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.\n\n---\n\n## Run tests\n\n```bash\npip install c3poh-for-claudecode[dev]\npytest tests/ -v\n```\n\n---\n\n## Roadmap\n\n- [ ] v0.2: Slack support\n- [ ] v0.2: Discord support\n- [ ] v0.2: Message history context (multi-turn conversations)\n- [ ] v0.3: `/status` and `/help` bot commands\n- [ ] v0.3: File/image send support\n- [ ] v1.0: Webhook mode (for production deployments)\n\n---\n\n## Related\n\n- [TinMan](https://github.com/andyuninvited/tinman_for_claudecode) — Heartbeat for Claude Code (the heart to C3Poh's voice)\n- [Heartbeat Templates](https://github.com/andyuninvited/heartbeat-templates) — Ready-to-use HEARTBEAT.md files\n- [Agent Blueprints](https://github.com/andyuninvited/agent-blueprints) — Starter templates for AI agents\n- [Claude Code](https://claude.ai/code) — the agentic CLI this is built for\n\n---\n\n## License\n\nGNU GPLv3 — copy-left, and let's evolve together.\n\nSee [LICENSE](LICENSE) for the full text.\n\n---\n\n*Built by [@andyuninvited](https://github.com/andyuninvited). Star if you've ever wished you could text your agent.*\n",
  "bytes": 8401,
  "sha": "47f6eb6762ef0a8b9752cc70dcb4f8240ebfbedad861ca200a379e6e13a2eb13",
  "repo_slug": "andyuninvited/c3poh_for_claudecode",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_andyuninvited_c3poh_for_claudecode_c3poh_f4fe0df1/readme"
}