{"id":47666163,"url":"https://github.com/alexei-led/ccgram","last_synced_at":"2026-04-06T10:02:11.877Z","repository":{"id":337638910,"uuid":"1154348823","full_name":"alexei-led/ccgram","owner":"alexei-led","description":"Telegram ↔ tmux bridge for Claude Code, Codex CLI, and Gemini CLI. Monitor output, respond to prompts, manage parallel sessions.  Control AI coding agents from your phone.","archived":false,"fork":false,"pushed_at":"2026-04-02T15:33:46.000Z","size":16993,"stargazers_count":38,"open_issues_count":1,"forks_count":17,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T00:41:48.700Z","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-04-02T15:33:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alexei-led/ccgram","commit_stats":null,"previous_names":["alexei-led/ccbot","alexei-led/ccgram"],"tags_count":85,"template":false,"template_full_name":null,"purl":"pkg:github/alexei-led/ccgram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexei-led%2Fccgram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexei-led%2Fccgram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexei-led%2Fccgram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexei-led%2Fccgram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexei-led","download_url":"https://codeload.github.com/alexei-led/ccgram/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexei-led%2Fccgram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31467985,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T08:36:52.050Z","status":"ssl_error","status_checked_at":"2026-04-06T08:36:51.267Z","response_time":112,"last_error":"SSL_read: 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-04-02T11:58:25.328Z","updated_at":"2026-04-06T10:02:11.861Z","avatar_url":"https://github.com/alexei-led.png","language":"Python","readme":"# CCGram — Command \u0026 Control Bot\n\n[![CI](https://github.com/alexei-led/ccgram/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/alexei-led/ccgram/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/ccgram)](https://pypi.org/project/ccgram/)\n[![Downloads](https://img.shields.io/pypi/dm/ccgram)](https://pypi.org/project/ccgram/)\n[![Python](https://img.shields.io/pypi/pyversions/ccgram)](https://pypi.org/project/ccgram/)\n[![Typed](https://img.shields.io/pypi/types/ccgram)](https://pypi.org/project/ccgram/)\n[![License](https://img.shields.io/github/license/alexei-led/ccgram)](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. CCGram 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), [Gemini CLI](https://github.com/google-gemini/gemini-cli), and plain shell sessions with LLM command generation.\n\n## Why CCGram?\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\nCCGram 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. CCGram 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. CCGram 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    T4[\"💬 Topic: server\"]\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    W4[\"🐚 window @3\u003cbr\u003eshell ↻ ready\"]\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  T4 -- \"text / voice →\" --\u003e W4\n  W4 -. \"← output\" .-\u003e T4\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 T4 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  style W4 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 directly to your agent topic\n- `/commands` shows commands supported by that topic's provider (Claude/Codex/Gemini/Shell)\n- Forwarded slash commands report provider mismatch errors (for example Claude-only `/cost` in Codex)\n- Command menu auto-switches per user/chat to the active topic provider after interaction\n- Interactive prompts (AskUserQuestion, ExitPlanMode, Permission) rendered as inline keyboards\n- Codex edit approvals are reformatted for Telegram readability (compact summary + short preview, with approval choices preserved)\n- Codex `/status` replies include a bot-side transcript snapshot (session + token/rate-limit stats) when Codex does not emit a normal transcript message\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- Voice message transcription via Whisper API (OpenAI, Groq) with confirm/discard keyboard\n- Sessions dashboard (`/sessions`) — overview of all sessions with status and kill buttons\n- Remote Control detection — 📡 topic badge when RC is active, one-tap activation from status keyboard\n- Action toolbar (`/toolbar`) — persistent inline buttons for RC, Screenshot, Esc, Notify, Ctrl-C\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- Entity-based 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, Google Gemini CLI, and Shell\n- Per-topic provider selection — different topics can use different agents simultaneously\n- Auto-detects provider from externally created tmux windows (process name, with ps-based TTY detection fallback for JS-runtime-wrapped CLIs like bun/node)\n- Provider-aware recovery (Continue/Resume buttons adapt to each provider's capabilities)\n- [Emdash](https://emdash.ai) integration — auto-discovers emdash tmux sessions; bind Telegram topics to emdash-managed agents with zero configuration\n\n**Shell provider**\n\n- Chat-first: type natural language → LLM generates a shell command → approve with one tap → output streams back\n- Raw mode: prefix with `!` to bypass the LLM and send commands directly\n- Voice-to-command: voice messages transcribed via Whisper, then routed through the LLM for command generation\n- Dangerous command detection with extra confirmation step\n- BYOK LLM — supports OpenAI, Anthropic, xAI, DeepSeek, Groq, Ollama (zero new dependencies)\n- See **[docs/providers.md](docs/providers.md#shell)** for LLM configuration\n\n**Extensibility**\n\n- Global Telegram menu includes bot commands + default provider commands (with `↗` prefix); provider-scoped menus auto-refresh per chat/user/topic context with Telegram-scope fallbacks\n- Tmux session auto-detection — when running inside tmux, auto-discovers the session and picks up existing agent windows; duplicate instance prevention\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 (or use the plain `shell` provider with no extra install required)\n\n### Install\n\n```bash\n# Recommended\nuv tool install ccgram\n\n# Alternatives\npipx install ccgram                   # pipx\nbrew install alexei-led/tap/ccgram    # Homebrew (macOS)\n```\n\n### Configure\n\n1. Create a Telegram bot via [@BotFather](https://t.me/BotFather)\n2. Configure bot settings in BotFather:\n   - **Allow Groups**: Enabled (Bot Settings \u003e Groups \u0026 Channels \u003e Allow Groups? \u003e Turn on)\n   - **Group Privacy**: Disabled (Bot Settings \u003e Groups \u0026 Channels \u003e Group Privacy \u003e Turn off) — _Required to see all messages in topics_\n   - **Topics**: Enabled (Bot Settings \u003e Groups \u0026 Channels \u003e Edit Topics \u003e Enable)\n3. Add the bot to a Telegram group with Topics enabled.\n4. **Promote the bot to Administrator** and ensure it has these permissions:\n   - **Create Topics** (required for the bot to automatically sync and manage session topics)\n   - **Pin Messages** (required for the General-topic usage hint)\n   - Note: the bot also uses **message reactions** in the General topic — this requires no extra permission.\n5. Create `~/.ccgram/.env`:\n\n```ini\nTELEGRAM_BOT_TOKEN=your_bot_token_here\nALLOWED_USERS=your_telegram_user_id\nCCGRAM_GROUP_ID=your_telegram_group_id\n```\n\n\u003e Get your user ID from [@userinfobot](https://t.me/userinfobot) on Telegram.\n\u003e Get the group ID by adding -100 in front of the **Peer ID** found in the Group Info (or use [@RawDataBot](https://t.me/RawDataBot)).\n\n### Install hooks (Claude Code only)\n\n```bash\nccgram hook --install\n```\n\nThis registers Claude Code hooks (SessionStart, Notification, Stop, StopFailure, SessionEnd, SubagentStart, SubagentStop, TeammateIdle, TaskCompleted) for automatic session tracking, instant interactive UI detection, API error alerting, session lifecycle cleanup, and agent team notifications. Not needed for Codex or Gemini — those providers are discovered from hookless transcripts and tmux window/provider detection.\n\n\u003e If hooks are missing, ccgram warns at startup with the fix command. Hooks are optional — terminal scraping works as fallback.\n\n### Configure LLM for Shell Provider (optional)\n\nTo enable natural language → shell command generation in shell topics, add an LLM provider:\n\n```ini\nCCGRAM_LLM_PROVIDER=openai   # or: anthropic, xai, deepseek, groq, ollama\n```\n\nSee **[docs/providers.md](docs/providers.md#llm-configuration)** for all options. Without an LLM, shell topics forward text as raw commands.\n\n### Run\n\n```bash\nccgram\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, Gemini, or Shell), then choose session mode (`✅ Standard` or `🚀 YOLO`), and you're connected.\n\n## Migrating from ccbot\n\nCCGram was previously named `ccbot`. If upgrading from v1.x:\n\n```bash\n# Install new package\npip install ccgram   # or: brew install alexei-led/tap/ccgram\n\n# Migrate config directory\nmv ~/.ccbot ~/.ccgram\n\n# Update environment variables: CCBOT_* → CCGRAM_*\n# Old CCBOT_* vars still work as fallback with deprecation warnings\n\n# Re-install hooks (replaces legacy \"ccbot hook\" entries)\nccgram hook --install\n```\n\n## Documentation\n\n- **[docs/guides.md](docs/guides.md)** — CLI reference, configuration, upgrading, multi-instance setup, session recovery, testing\n- **[docs/providers.md](docs/providers.md)** — Provider details (Claude, Codex, Gemini, Shell), session modes, LLM configuration, custom launch commands\n\n## Development\n\n```bash\ngit clone https://github.com/alexei-led/ccgram.git\ncd ccgram\nuv sync --extra dev\n\nmake check        # fmt + lint + typecheck + unit + integration tests\nmake test-e2e     # E2E tests (requires agent CLIs, see docs/guides.md)\n```\n\n## Acknowledgments\n\nCCGram 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","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexei-led%2Fccgram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexei-led%2Fccgram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexei-led%2Fccgram/lists"}