{"id":45884448,"url":"https://github.com/alexei-led/ccbot","last_synced_at":"2026-03-08T15:01:00.128Z","repository":{"id":337638910,"uuid":"1154348823","full_name":"alexei-led/ccbot","owner":"alexei-led","description":"Control AI code agents (claude, codex, gemini) from Telegram — monitor output, respond to prompts, manage sessions via tmux. Supports multiple groups and bot instances.","archived":false,"fork":false,"pushed_at":"2026-02-27T13:26:05.000Z","size":16328,"stargazers_count":1,"open_issues_count":13,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-27T18:52:02.714Z","etag":null,"topics":["ai-coding","claude-code","cli","codex","codex-cli","developer-tools","gemini","gemini-cli","python","telegram","telegram-bot","tmux"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"six-ddc/ccbot","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexei-led.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-10T09:35:58.000Z","updated_at":"2026-02-27T13:26:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alexei-led/ccbot","commit_stats":null,"previous_names":["alexei-led/ccbot"],"tags_count":37,"template":false,"template_full_name":null,"purl":"pkg:github/alexei-led/ccbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexei-led%2Fccbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexei-led%2Fccbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexei-led%2Fccbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexei-led%2Fccbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexei-led","download_url":"https://codeload.github.com/alexei-led/ccbot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexei-led%2Fccbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29977966,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T16:35:47.903Z","status":"ssl_error","status_checked_at":"2026-03-01T16:35:44.899Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding","claude-code","cli","codex","codex-cli","developer-tools","gemini","gemini-cli","python","telegram","telegram-bot","tmux"],"created_at":"2026-02-27T15:15:03.421Z","updated_at":"2026-03-01T18:01:01.944Z","avatar_url":"https://github.com/alexei-led.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CCBot — Command \u0026 Control Bot\n\n[![CI](https://github.com/alexei-led/ccbot/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/alexei-led/ccbot/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/ccbot)](https://pypi.org/project/ccbot/)\n[![Downloads](https://img.shields.io/pypi/dm/ccbot)](https://pypi.org/project/ccbot/)\n[![Python](https://img.shields.io/pypi/pyversions/ccbot)](https://pypi.org/project/ccbot/)\n[![Typed](https://img.shields.io/pypi/types/ccbot)](https://pypi.org/project/ccbot/)\n[![License](https://img.shields.io/github/license/alexei-led/ccbot)](LICENSE)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\nControl AI coding agents from your phone. CCBot bridges Telegram to tmux — monitor output, respond to prompts, and manage sessions without touching your computer. Supports [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex CLI](https://github.com/openai/codex), and [Gemini CLI](https://github.com/google-gemini/gemini-cli).\n\n## Why CCBot?\n\nAI coding agents run in your terminal. When you step away — commuting, on the couch, or just away from your desk — the session keeps working, but you lose visibility and control.\n\nCCBot fixes this. The key insight: it operates on **tmux**, not any agent's SDK. Your agent process stays exactly where it is, in a tmux window on your machine. CCBot reads its output and sends keystrokes to it. This means:\n\n- **Desktop to phone, mid-conversation** — your agent is working on a refactor? Walk away and keep monitoring from Telegram\n- **Phone back to desktop, anytime** — `tmux attach` and you're back in the terminal with full scrollback\n- **Multiple sessions in parallel** — Each Telegram topic maps to a separate tmux window, each can run a different agent\n\nOther Telegram bots wrap agent SDKs to create isolated API sessions that can't be resumed in your terminal. CCBot is different — it's a thin control layer over tmux, so the terminal remains the source of truth.\n\n## How It Works\n\n```mermaid\ngraph LR\n  subgraph phone[\"📱 Telegram Group\"]\n    T1[\"💬 Topic: api\"]\n    T2[\"💬 Topic: ui\"]\n    T3[\"💬 Topic: docs\"]\n  end\n\n  subgraph machine[\"🖥️ Your Machine — tmux\"]\n    W1[\"⚡ window @0\u003cbr\u003eclaude ↻ running\"]\n    W2[\"⚡ window @1\u003cbr\u003ecodex ↻ running\"]\n    W3[\"⚡ window @2\u003cbr\u003egemini ↻ running\"]\n  end\n\n  T1 -- \"text →\" --\u003e W1\n  W1 -. \"← responses\" .-\u003e T1\n  T2 -- \"text →\" --\u003e W2\n  W2 -. \"← responses\" .-\u003e T2\n  T3 -- \"text →\" --\u003e W3\n  W3 -. \"← responses\" .-\u003e T3\n\n  style phone fill:#e8f4fd,stroke:#0088cc,stroke-width:2px,color:#333\n  style machine fill:#f0faf0,stroke:#2ea44f,stroke-width:2px,color:#333\n  style T1 fill:#fff,stroke:#0088cc,stroke-width:1px,color:#333\n  style T2 fill:#fff,stroke:#0088cc,stroke-width:1px,color:#333\n  style T3 fill:#fff,stroke:#0088cc,stroke-width:1px,color:#333\n  style W1 fill:#fff,stroke:#2ea44f,stroke-width:1px,color:#333\n  style W2 fill:#fff,stroke:#2ea44f,stroke-width:1px,color:#333\n  style W3 fill:#fff,stroke:#2ea44f,stroke-width:1px,color:#333\n```\n\nEach Telegram Forum topic binds to one tmux window running an agent CLI. Messages you type in the topic are sent as keystrokes to the tmux pane; the agent's output is parsed from session transcripts and delivered back as Telegram messages.\n\n## Features\n\n**Session control**\n\n- Send messages and `/commands` directly to your agent (`/clear`, `/compact`, `/cost`, etc.)\n- Interactive prompts (AskUserQuestion, ExitPlanMode, Permission) rendered as inline keyboards\n- Multi-pane support — auto-detects blocked panes, surfaces prompts, `/panes` command for overview\n- Terminal screenshots — capture the current pane (or any specific pane) as a PNG image\n- Sessions dashboard (`/sessions`) — overview of all sessions with status and kill buttons\n\n**Real-time monitoring**\n\n- Assistant responses, thinking content, tool use/result pairs, and command output\n- Live status line showing what the agent is currently doing\n- MarkdownV2 formatting with automatic plain text fallback\n\n**Session management**\n\n- Directory browser for creating new sessions from Telegram\n- Auto-sync: create a tmux window manually and the bot auto-creates a matching topic\n- Fresh/Continue/Resume recovery when a session dies\n- Message history with paginated browsing (`/history`)\n- Persistent state — bindings and read offsets survive restarts\n\n**Multi-provider support**\n\n- Claude Code (default), OpenAI Codex CLI, and Google Gemini CLI\n- Per-topic provider selection — different topics can use different agents simultaneously\n- Auto-detects provider from externally created tmux windows\n- Provider-aware recovery (Continue/Resume buttons adapt to each provider's capabilities)\n\n**Extensibility**\n\n- Auto-discovers agent skills and custom commands into the Telegram menu\n- Multi-instance support — run separate bots per Telegram group on the same machine\n- Configurable via environment variables\n\n## Quick Start\n\n### Prerequisites\n\n- **Python 3.14+**\n- **tmux** — installed and in PATH\n- **At least one agent CLI** — `claude` (default), `codex`, or `gemini` installed and authenticated\n\n### Install\n\n```bash\n# Recommended\nuv tool install ccbot\n\n# Alternatives\npipx install ccbot                   # pipx\nbrew install alexei-led/tap/ccbot    # Homebrew (macOS)\n```\n\n### Configure\n\n1. Create a Telegram bot via [@BotFather](https://t.me/BotFather)\n2. Enable **Topics** in your bot (BotFather \u003e Bot Settings \u003e Groups \u003e Topics in Groups \u003e Enable)\n3. Add the bot to a Telegram group that has Topics enabled\n4. Create `~/.ccbot/.env`:\n\n```ini\nTELEGRAM_BOT_TOKEN=your_bot_token_here\nALLOWED_USERS=your_telegram_user_id\n```\n\n\u003e Get your user ID from [@userinfobot](https://t.me/userinfobot) on Telegram.\n\n### Install hooks (Claude Code only)\n\n```bash\nccbot hook --install\n```\n\nThis registers 7 Claude Code hooks (SessionStart, Notification, Stop, SubagentStart, SubagentStop, TeammateIdle, TaskCompleted) for automatic session tracking, instant interactive UI detection, real-time status updates, and agent team notifications. Not needed for Codex or Gemini — those providers are auto-detected from running processes.\n\n\u003e If hooks are missing, ccbot warns at startup with the fix command. Hooks are optional — terminal scraping works as fallback.\n\n### Run\n\n```bash\nccbot\n```\n\nOpen your Telegram group, create a new topic, send a message — a directory browser appears. Pick a project directory, choose your agent (Claude, Codex, or Gemini), and you're connected.\n\n## Documentation\n\nSee **[docs/guides.md](docs/guides.md)** for CLI reference, configuration, upgrading, multi-instance setup, session recovery, and more.\n\n## Acknowledgments\n\nCCBot started as a fork of [ccbot](https://github.com/six-ddc/ccbot) by [six-ddc](https://github.com/six-ddc), who created the original Telegram-to-Claude-Code bridge. This project has since been rewritten and developed independently with multi-provider support, topic-based architecture, interactive UI, and a comprehensive test suite. Thanks to six-ddc for the initial idea and implementation.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexei-led%2Fccbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexei-led%2Fccbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexei-led%2Fccbot/lists"}