---
name: Архитектура CCBot
description: Архитектура CCBot — Telegram-мост к Claude Code через tmux
type: reference
tags:
  - ccbot
  - telegram
  - architecture
---

# CCBot — Telegram ↔ Claude Code мост

## Общая схема
Даня общается с Claude Code через Telegram, используя CCBot — Python-бот на `python-telegram-bot`.

## Ключевые компоненты
- **Пакет:** установлен через `uv tool` из `github.com/six-ddc/ccmux.git`
- **Код:** `/home/serv3090/.local/share/uv/tools/ccbot/lib/python3.12/site-packages/ccbot/`
- **Конфиг:** `/home/serv3090/.ccbot/.env` (токен бота, allowed users, OpenAI key)
- **Состояние:** `/home/serv3090/.ccbot/state.json` (thread bindings, window states, group_chat_ids)
- **Сервис:** systemd user unit `ccbot.service`

## Telegram-маршрутизация
- **Группа:** chat_id `-1003792334275`
- **User ID Дани:** `562684241`
- **Топики:** каждый topic (message_thread_id) привязан к tmux-окну (Claude сессии)
- Привязки хранятся в `state.json` → `thread_bindings`

## Архитектура сообщений
- CCBot мониторит JSONL-файлы Claude сессий через `SessionMonitor`
- Новые сообщения парсятся `TranscriptParser` и ставятся в очередь `MessageQueue`
- Очередь отправляет в Telegram с fallback MarkdownV2 → plain text
- Поддержка: текст, thinking, tool_use/tool_result, изображения, голосовые (входящие через OpenAI STT)

## Ключевые модули
- `bot.py` — хэндлеры команд и сообщений
- `session_monitor.py` — мониторинг JSONL сессий
- `session.py` — маппинг window↔session↔thread
- `handlers/message_queue.py` — очередь отправки с merge и flood control
- `handlers/message_sender.py` — send_with_fallback, safe_reply
- `tmux_manager.py` — управление tmux окнами
- `transcribe.py` — голосовая транскрипция (OpenAI STT) + описание изображений (GPT-4o-mini vision)

## Настройки `.env`
- `CCBOT_SHOW_USER_MESSAGES=false` — не дублировать сообщения пользователя обратно в чат
- `CCBOT_SHOW_TOOL_CALLS=false` — не показывать уведомления о tool_use/tool_result
- Голосовые: транскрипция без эхо в чат (🎤 убран)
- Фото: describe_image через GPT-4o-mini vision → краткое описание `📷 ...` в чат
- Thinking-блоки обрабатываются как статус-обновления (редактируются на месте, заменяются ответом)