I built CCBot (Command & Control Bot) — a Telegram bot that gives you remote control over AI coding agents (Claude Code, OpenAI Codex CLI, Gemini CLI) running in tmux on your machine.
The problem: AI coding agents run in your terminal. When you step away — commuting, on the couch, at dinner — the session keeps working, but you lose visibility and control. Permission prompts pile up. You miss when the agent finishes or gets stuck.
=The approach: CCBot doesn't wrap agent SDKs or create isolated API sessions. It sits on top of tmux. Your agent process stays exactly where it is, in a terminal window. CCBot reads its output (from session transcripts, terminal scraping, and hook events) and sends keystrokes to it. You can tmux attach at any time and pick up where you left off — nothing is abstracted away.
How it works: Each Telegram Forum topic maps to one tmux window running one agent. Messages you type go in as keystrokes; the agent's responses come back as Telegram messages with MarkdownV2 formatting. Interactive prompts (permissions, plan mode, ask-user questions) are rendered as inline keyboard buttons you can tap.
Key features:
- Multi-provider — Claude Code, Codex, and Gemini in the same session. Each topic can run a different agent. Auto-detects provider from running processes.
- Interactive UI from your phone — Permission prompts, AskUserQuestion, ExitPlanMode rendered as tap-to-respond inline keyboards. No more returning to your desk just to hit "y".
- Real-time monitoring — Live status line, assistant responses, thinking content, tool use/result pairs streamed to Telegram.
- Hook-based event system — 5 Claude Code hook event types (SessionStart, Notification, Stop, SubagentStart, SubagentStop) for instant detection — no polling delay for interactive prompts.
- Session lifecycle — Directory browser to create sessions, auto-sync for manually created tmux windows, Fresh/Continue/Resume recovery when sessions die, paginated message history.
- Terminal screenshots — Capture the current pane as a PNG image, right from Telegram.
- Sessions dashboard — Overview of all running sessions with status and kill buttons.
- Agent command passthrough — Send /clear, /compact, /cost, or any slash command directly to the agent.
- Multi-instance — Run separate bots per Telegram group on the same machine.
Install: `uv tool install ccbot` or `brew install alexei-led/tap/ccbot`
Credits: CCBot started as a fork of https://github.com/six-ddc/ccbot, who created the original Telegram-to-Claude-Code bridge — a clever idea that I immediately wanted to build on. The project has since been rewritten with multi-provider support, topic-based architecture, interactive UI, hook event system, and a 1250+ test suite. Thanks to six-ddc for the original idea and implementation that got this started.
Tech: Python, python-telegram-bot, tmux, pyte (VT100 emulation), structlog. MIT licensed.
Would love feedback — especially from anyone running AI agents on remote machines or headless setups.
1 comment
[ 2.9 ms ] story [ 11.0 ms ] threadI built CCBot (Command & Control Bot) — a Telegram bot that gives you remote control over AI coding agents (Claude Code, OpenAI Codex CLI, Gemini CLI) running in tmux on your machine.
The problem: AI coding agents run in your terminal. When you step away — commuting, on the couch, at dinner — the session keeps working, but you lose visibility and control. Permission prompts pile up. You miss when the agent finishes or gets stuck.
=The approach: CCBot doesn't wrap agent SDKs or create isolated API sessions. It sits on top of tmux. Your agent process stays exactly where it is, in a terminal window. CCBot reads its output (from session transcripts, terminal scraping, and hook events) and sends keystrokes to it. You can tmux attach at any time and pick up where you left off — nothing is abstracted away.
How it works: Each Telegram Forum topic maps to one tmux window running one agent. Messages you type go in as keystrokes; the agent's responses come back as Telegram messages with MarkdownV2 formatting. Interactive prompts (permissions, plan mode, ask-user questions) are rendered as inline keyboard buttons you can tap.
Key features:
- Multi-provider — Claude Code, Codex, and Gemini in the same session. Each topic can run a different agent. Auto-detects provider from running processes. - Interactive UI from your phone — Permission prompts, AskUserQuestion, ExitPlanMode rendered as tap-to-respond inline keyboards. No more returning to your desk just to hit "y". - Real-time monitoring — Live status line, assistant responses, thinking content, tool use/result pairs streamed to Telegram. - Hook-based event system — 5 Claude Code hook event types (SessionStart, Notification, Stop, SubagentStart, SubagentStop) for instant detection — no polling delay for interactive prompts. - Session lifecycle — Directory browser to create sessions, auto-sync for manually created tmux windows, Fresh/Continue/Resume recovery when sessions die, paginated message history. - Terminal screenshots — Capture the current pane as a PNG image, right from Telegram. - Sessions dashboard — Overview of all running sessions with status and kill buttons. - Agent command passthrough — Send /clear, /compact, /cost, or any slash command directly to the agent. - Multi-instance — Run separate bots per Telegram group on the same machine.
Install: `uv tool install ccbot` or `brew install alexei-led/tap/ccbot`
Credits: CCBot started as a fork of https://github.com/six-ddc/ccbot, who created the original Telegram-to-Claude-Code bridge — a clever idea that I immediately wanted to build on. The project has since been rewritten with multi-provider support, topic-based architecture, interactive UI, hook event system, and a 1250+ test suite. Thanks to six-ddc for the original idea and implementation that got this started.
Tech: Python, python-telegram-bot, tmux, pyte (VT100 emulation), structlog. MIT licensed.
Would love feedback — especially from anyone running AI agents on remote machines or headless setups.