Metadata-Version: 2.4
Name: ccbot
Version: 0.2.0
Summary: Telegram bot that bridges Telegram Forum topics to Claude Code sessions via tmux
Project-URL: Homepage, https://github.com/alexei-led/ccbot
Project-URL: Repository, https://github.com/alexei-led/ccbot
Project-URL: Issues, https://github.com/alexei-led/ccbot/issues
Project-URL: Changelog, https://github.com/alexei-led/ccbot/blob/main/CHANGELOG.md
Author-email: Alexei Ledenev <alexei.led@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
Requires-Python: >=3.14
Requires-Dist: aiofiles>=24.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: libtmux>=0.37.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-telegram-bot>=21.0
Requires-Dist: telegramify-markdown>=0.5.0
Provides-Extra: dev
Requires-Dist: pyright>=1.1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# CCBot

[![CI](https://github.com/alexei-led/ccbot/actions/workflows/ci.yml/badge.svg)](https://github.com/alexei-led/ccbot/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/ccbot)](https://pypi.org/project/ccbot/)
[![Python](https://img.shields.io/pypi/pyversions/ccbot)](https://pypi.org/project/ccbot/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![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)

Control Claude Code sessions remotely via Telegram — monitor, interact, and manage AI coding sessions running in tmux.

## Contents

- [Why CCBot?](#why-ccbot)
- [Features](#features)
- [Quick Start](#quick-start)
- [Documentation](#documentation)
- [Credits](#credits)
- [License](#license)

## Why CCBot?

Claude Code runs in your terminal. When you step away from your computer — commuting, on the couch, or just away from your desk — the session keeps working, but you lose visibility and control.

CCBot solves this by letting you **seamlessly continue the same session from Telegram**. 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. This means:

- **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.
- **Run multiple sessions in parallel** — Each Telegram topic maps to a separate tmux window, so you can juggle multiple projects from one chat group.

Other Telegram bots for Claude Code typically wrap the Claude Code SDK to create separate API sessions. Those sessions are isolated — you can't resume them in your terminal. CCBot takes a different approach: it's just a thin control layer over tmux, so the terminal remains the source of truth and you never lose the ability to switch back.

## Features

- **Topic-based sessions** — Each Telegram topic maps 1:1 to a tmux window and Claude session
- **Real-time notifications** — Assistant responses, thinking content, tool use/result, and local command output
- **Interactive UI** — Navigate AskUserQuestion, ExitPlanMode, and Permission Prompts via inline keyboard
- **Send messages** — Forward text to Claude Code via tmux keystrokes
- **Slash command forwarding** — Any `/command` is forwarded to Claude Code (e.g. `/clear`, `/compact`, `/cost`)
- **Sessions dashboard** — Overview of all active sessions with status and quick actions
- **Message history** — Browse conversation history with pagination (newest first)
- **Auto-sync tmux windows** — Create a tmux window and start Claude manually; the bot auto-creates a matching Telegram topic
- **Auto-discovery** — Claude Code skills and custom commands appear in the Telegram menu automatically
- **Persistent state** — Thread bindings and read offsets survive restarts

## Quick Start

### 1. Prerequisites

- **tmux** — must be installed and available in PATH
- **Claude Code** — the CLI tool (`claude`) must be installed

### 2. Install

```bash
# Using Homebrew (macOS)
brew install alexei-led/tap/ccbot

# From PyPI (recommended for Linux)
uv tool install ccbot

# Or using pipx
pipx install ccbot

# Or from source
uv tool install git+https://github.com/alexei-led/ccbot.git
```

### 3. Configure

Create a Telegram bot via [@BotFather](https://t.me/BotFather), then enable **Threaded Mode** (BotFather > your bot > Settings > Bot Settings).

Create `~/.ccbot/.env`:

```ini
TELEGRAM_BOT_TOKEN=your_bot_token_here
ALLOWED_USERS=your_telegram_user_id
```

### 4. Install the session hook

```bash
ccbot hook --install
```

This lets the bot auto-track which Claude session runs in each tmux window.

### 5. Run

```bash
ccbot
```

Open your Telegram group, create a new topic, send a message — a directory browser appears. Pick a project directory and you're connected to Claude Code.

## Documentation

| Guide                        | Description                                           |
| ---------------------------- | ----------------------------------------------------- |
| **[Guides](docs/guides.md)** | Multi-instance setup, manual tmux usage, data storage |

## Credits

CCBot is a maintained fork of [ccbot](https://github.com/six-ddc/ccbot) by [six-ddc](https://github.com/six-ddc). See [FORK.md](FORK.md) for details on the fork history and divergences.

## License

[MIT](LICENSE) — see LICENSE file for details.
