CCBot — Summary

CCBot is a Python tool that creates a Telegram-to-tmux bridge for Claude Code sessions: one Telegram topic maps 1:1 to one tmux window, which maps 1:1 to one Claude Code session. Unlike Telegram bots that wrap the Claude Code SDK (creating isolated API sessions), CCBot operates directly on tmux — it reads terminal output via libtmux and sends keystrokes back, so the tmux session remains the source of truth and the developer can attach/detach from the terminal at any time. Features include real-time notifications for assistant responses, tool calls, and permissions; interactive UI buttons for ExitPlanMode and AskUserQuestion; voice message transcription via OpenAI; multi-session management via thread-per-topic; a SessionStart hook auto-associating tmux windows with Claude sessions; and persistent state surviving restarts. Distributed as a pip/uv package (ccbot), it ships a ccbot CLI binary and a ccbot hook subcommand for Claude Code hook integration. Compared to the seeds, CCBot is closest to agent-os or claude-conductor in its "minimal infrastructure, no prompt framework" philosophy, but uniquely occupies the Telegram-channel remote-control niche.

CCBot — Overview

Origin

Personal project by six-ddc. 19 contributors. 250 stars. Python. MIT license. Active development, last commit 2026-05-21.

Philosophy

"The key insight is that it operates on tmux, not the Claude Code SDK. Your Claude Code process stays exactly where it is, in a tmux window on your machine. CCBot simply reads its output and sends keystrokes to it."

"Switch from desktop to phone mid-conversation — Claude is working on a refactor? Walk away, keep monitoring and responding from Telegram."

"Switch back to desktop anytime — Since the tmux session was never interrupted, just tmux attach and you're back in the terminal with full scrollback and context."

"In fact, CCBot itself was built this way — iterating on itself through Claude Code sessions monitored and driven from Telegram via CCBot."

Core Design Decision: tmux as source of truth

Other Telegram bots for Claude Code wrap the SDK to create separate API sessions — those sessions are isolated from the terminal and can't be resumed there. CCBot takes the opposite approach: tmux is the source of truth, the terminal is never interrupted, and Telegram is just a remote view+control interface.

Multi-Language Documentation

README in English, Chinese, and Russian.

CCBot — Architecture

Distribution

• pip/uv: uv tool install git+https://github.com/six-ddc/ccmux.git (note: repo URL in README uses ccmux not ccbot)
• pipx: pipx install git+https://github.com/six-ddc/ccmux.git
• Source: git clone && uv sync

Platform

• Linux/macOS (requires tmux)
• Python >= 3.12

Architecture Diagram

Telegram (user's phone)
    ↓ Bot API (HTTP polling)
CCBot daemon (Python, asyncio)
    ↓ libtmux
tmux session → window → pane
    ↓ Claude Code process (unmodified)

Directory Structure

src/ccbot/
  main.py          — Entry point: dispatches to hook.hook_main() or bot polling
  bot.py           — Telegram bot handlers (commands, callbacks, messages)
  config.py        — Configuration from ~/.ccbot/.env
  hook.py          — Claude Code SessionStart hook handler + installer
  tmux_manager.py  — libtmux session/window management
  session.py       — Session state
  session_monitor.py — Terminal output monitoring + polling
  monitor_state.py — State machine for monitoring
  terminal_parser.py — Parse terminal output for Claude responses
  transcript_parser.py — Parse conversation transcripts
  handlers/        — Telegram handler modules
    callback_data.py
    message_queue.py
    message_sender.py
    history.py
    directory_browser.py
    interactive_ui.py
    status_polling.py
    response_builder.py
  telegram_sender.py — Safe message sending helpers
  screenshot.py    — Terminal screenshot
  transcribe.py    — Voice message transcription (OpenAI)
  markdown_v2.py   — Telegram MarkdownV2 formatting
  utils.py         — Utilities (ccbot_dir, etc.)
tests/             — pytest tests

Configuration

~/.ccbot/.env:

TELEGRAM_BOT_TOKEN=...
ALLOWED_USERS=123456789
# Optional:
TMUX_SESSION_NAME=ccbot       # default
CLAUDE_COMMAND=claude          # command for new windows
MONITOR_POLL_INTERVAL=2.0      # seconds
OPENAI_API_KEY=...             # for voice transcription

Required Runtime

• Python >= 3.12
• tmux (in PATH)
• claude CLI (in PATH)
• Telegram bot token (from @BotFather)
• Telegram group with Threaded Mode enabled

CCBot — Components

CLI Binary

Telegram Bot Commands

Interactive UI (Inline Keyboard Buttons)

• AskUserQuestion — Navigate agent permission prompts via inline keyboard
• ExitPlanMode — Button to exit Claude Code's plan mode
• Permission prompts — Approve/deny via inline buttons
• Directory browser — Browse filesystem to create new Claude sessions
• History pagination — Navigate message history

Claude Code Hook

ccbot hook installs a SessionStart hook that writes window_id → session_id mappings to ~/.ccbot/session_map.json. This auto-associates tmux windows with Claude sessions even after /clear or session restarts.

Hook entry in ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {"hooks": [{"type": "command", "command": "ccbot hook", "timeout": 5}]}
    ]
  }
}

State Files

• ~/.ccbot/.env — Configuration
• ~/.ccbot/session_map.json — tmux window ↔ Claude session ID mappings
• Thread bindings and read offsets — persist in memory across restarts (exact path unknown)

Key Dependencies

• python-telegram-bot[rate-limiter]>=21.0 — Telegram Bot API
• libtmux>=0.37.0 — tmux control library
• chatgpt-md-converter (chatgpt_md_converter) — HTML message formatting
• httpx — HTTP client
• Pillow — Screenshot image handling
• aiofiles — Async file I/O
• telegramify-markdown — Markdown → Telegram-safe format

CCBot — Uniqueness

differs_from_seeds

CCBot has no meaningful parallel in the 11 seeds. The seeds address agent methodology, prompting, and memory — CCBot addresses remote session control via Telegram. The closest analogy is claude-conductor (Archetype 4: markdown scaffold) in that both are minimal infrastructure tools, but claude-conductor focuses on structured markdown templates while CCBot focuses on bridging a messaging app to a terminal. CCBot is architecturally inverted from IM.codes (also in this batch): IM.codes builds a full three-tier server infrastructure for remote access, whereas CCBot is a thin Python daemon that directly controls tmux on the same machine via Telegram Bot API.

Positioning

CCBot is the Telegram channel of the "remote control for coding agents" design space. It targets developers who already use Telegram and want zero infrastructure overhead — no servers, no Docker, no self-hosting. Just a bot token and a Python package. The constraint is locality: CCBot requires Claude Code to run on the same machine as the CCBot daemon (no remote machine support without SSH).

Observable Failure Modes

1. Same-machine requirement: CCBot must run on the machine where Claude Code runs; no built-in remote machine support
2. VPS permissions: on headless servers, Claude Code requires --dangerously-skip-permissions (documented: CLAUDE_COMMAND=IS_SANDBOX=1 claude --dangerously-skip-permissions)
3. Poll-based monitoring: 2-second poll interval means up to 2s notification delay; not real-time like PTY streaming
4. tmux dependency: requires tmux to be running
5. Telegram bot dependencies: requires BotFather setup, group with Threaded Mode enabled
6. Message formatting: always HTML via chatgpt-md-converter; no MarkdownV2 runtime switch
7. Single maintainer: 19 contributors but project is one person's personal tool

What Is Genuinely Novel

• tmux-as-source-of-truth design: developer can always tmux attach and resume in terminal — no lock-in to bot interface
• Multi-topic = multi-session: Telegram's threaded topics map naturally to parallel agent sessions
• Interactive UI for Claude Code primitives (AskUserQuestion, ExitPlanMode, permission prompts) via Telegram inline keyboards
• Voice message support with configurable OpenAI API endpoint (supports local Whisper-compatible APIs via OPENAI_BASE_URL)
• Self-referential origin story: "CCBot itself was built this way — iterating on itself through Claude Code sessions monitored and driven from Telegram via CCBot"