Skip to content

README.ru.md

Latest commit

 

History

History
208 lines (169 loc) · 12.7 KB

README.ru.md

File metadata and controls

208 lines (169 loc) · 12.7 KB
Raw

TeleClaude

Claude Code отключили от Telegram? Мы всё подключим обратно — на ваших условиях.

Маршрутизация топиков Telegram в изолированные сессии Claude Code с постоянной памятью

Bun TypeScript Telegram Bot API MIT License

English

TeleClaude превращает Telegram-супергруппу с топиками в мультипроектного AI-ассистента. Каждый топик получает свой процесс Claude Code с изолированной рабочей директорией, постоянной памятью и автоматическим управлением контекстом.

Self-hosted замена Telegram-интеграции OpenClaw — Claude Code работает локально, с полным доступом к файловой системе. Использует ту же OAuth-авторизацию, что и Claude Code на вашем компьютере: если у вас есть подписка Claude (Max, Pro, Team) — дополнительных расходов на API нет. Можно переключаться между моделями Claude (Opus, Sonnet, Haiku) или использовать локальные модели через Claude Code.

Как это работает

Telegram-супергруппа (режим форума)
│
├── Топик "Backend API"    →  Claude Code  →  ~/Projects/backend-api/
├── Топик "Лендинг"        →  Claude Code  →  ~/Projects/landing/
├── Топик "DevOps"         →  Claude Code  →  ~/Projects/devops/
└── Топик "Новая фича"     →  автоматически создает директорию проекта

Вы пишете в топик Telegram — Claude Code отвечает в том же топике, с полным доступом к файлам проекта.

Возможности

Функция Описание
Маршрутизация по топикам Каждый топик = изолированный процесс Claude Code со своей рабочей директорией
Постоянная память Три уровня: личность (SOUL.md) + общая (main-memory.md) + по топику (topic-memory.md)
Автосоздание проектов Новые топики автоматически получают директорию из шаблонов
Компрессия контекста Автоматическое сохранение ключевых решений в память при росте контекста
Дедупликация памяти Периодическая кросс-файловая очистка дублирующейся информации
Голосовые сообщения Транскрипция через локальный Whisper ASR (опционально)
Непрерывность сессий Флаг --continue сохраняет контекст между сообщениями
Управление процессами Настраиваемый TTL, лимиты параллельных процессов, очистка простаивающих
8 команд бота /help /status /ttl /name /compact /reset /kill /memory
Без API-ключа OAuth от вашего Claude Code — работает с любой подпиской Claude
Переключение моделей Opus, Sonnet, Haiku или локальные модели через Claude Code

Быстрый старт

1. Установка

git clone https://github.com/devladpopov/teleclaude.git
cd teleclaude
bun install

2. Настройка

cp .env.example .env                              # Добавьте токен Telegram-бота
cp config/settings.example.json config/settings.json  # Укажите свой Telegram user ID
cp config/topics.example.json config/topics.json      # Заполняется ботом автоматически

3. Шаблоны

cp templates/SOUL.example.md templates/SOUL.md
cp templates/main-memory.example.md templates/main-memory.md
# Отредактируйте оба файла — задайте личность бота и общую память

4. Запуск

bun run start

Добавьте бота в Telegram-супергруппу с включенными топиками. Отправьте сообщение в любой топик — бот создаст директорию проекта и ответит.

Команды бота

Команда Описание
/help Список всех команд
/status Активные процессы, TTL, статус функций
/ttl N Таймаут простоя (1–1440 минут)
/name <имя> Переименовать топик (обновляет маппинг проекта)
/compact Принудительная компрессия — сохранить решения в память
/reset Сброс сессии — новый диалог с сохраненной памятью
/kill Убить процесс Claude Code текущего топика
/memory Статистика файлов памяти и текущей сессии

Архитектура

┌──────────────────┐
│  Telegram Bot API │
└────────┬─────────┘
         │
┌────────▼─────────────────────────┐
│  Router (grammy)                 │
│  ├── Маршрутизация по топикам    │
│  ├── Обработка команд            │
│  ├── Инъекция контекста памяти   │
│  ├── Компрессия контекста        │
│  ├── Менеджер памяти (дедуп)     │
│  ├── Фабрика проектов (шаблоны)  │
│  └── Whisper-клиент (опц.)       │
└────────┬─────────────────────────┘
         │
┌────────▼─────────────────────────┐
│  Менеджер процессов              │
│  ├── Спавн процесса на сообщение │
│  ├── Передача через stdin        │
│  ├── Непрерывность сессий        │
│  ├── TTL и очистка               │
│  └── Лимиты параллелизма         │
└────────┬─────────────────────────┘
         │
┌────────▼─────────────────────────┐
│  Claude Code CLI                 │
│  Один процесс на топик           │
│  Изолированная рабочая директория │
│  Полный доступ к файлам          │
└──────────────────────────────────┘

Система памяти

Каждый проект-топик поддерживает трехуровневую иерархию памяти:

project/
├── SOUL.md              # Личность и правила общения бота
├── main-memory.md       # Общий контекст всех проектов (симлинк)
├── topic-memory.md      # Память топика (обновляется Claude)
├── CLAUDE.md            # Инструкции проекта для Claude Code
└── memory/
    ├── people/          # Люди и контакты
    ├── services/        # Документация инфраструктуры
    ├── shared/          # Кросс-проектные гайды
    └── projects/        # Контекст конкретных проектов

Конфигурация

settings.json

Ключ Описание По умолчанию
telegram.allowedUsers Разрешенные Telegram user ID []
processes.ttlMinutes Таймаут простоя 30
processes.maxConcurrent Макс. параллельных процессов 5
processes.claudePath Путь к Claude Code CLI claude
compaction.enabled Автокомпрессия контекста true
memory.enabled Периодическая ревизия памяти true
memory.deduplication Кросс-файловая дедупликация true
whisper.enabled Транскрипция голоса false
projectsRoot Корневая директория проектов —

Требования

  • Bun 1.0+
  • Claude Code CLI — установлен и авторизован (OAuth-логин)
  • Любая подписка Claude (Max, Pro, Team) — или API-ключ
  • Токен Telegram-бота от @BotFather
  • Telegram-супергруппа с включенными топиками (режим форума)
  • (Опционально) Whisper ASR на localhost:9000

Как работает авторизация: TeleClaude не требует API-ключа. Он запускает процессы Claude Code CLI, которые используют вашу существующую OAuth-сессию — точно так же, как вы используете Claude Code в терминале. Если вы залогинены в Claude Code — TeleClaude просто работает.

Безопасность

  • Обрабатываются только сообщения от пользователей из allowedUsers
  • ANTHROPIC_API_KEY удаляется из окружения дочерних процессов
  • Токен бота, настройки и маппинг топиков в gitignore
  • Каждый процесс Claude Code работает в изолированной директории

Сравнение с OpenClaw

TeleClaude OpenClaw
Хостинг Самостоятельный (ваша машина) Облачный сервис
AI-бэкенд Claude Code CLI (полный доступ к файлам) Через API
Авторизация OAuth (ваша подписка Claude) Управляемая
Стоимость Бесплатно с любой подпиской Claude Отдельная подписка
Модели Opus/Sonnet/Haiku + локальные модели Зависит от провайдера
Память Файловая, постоянная, кросс-проектная Встроенная
Кастомизация Полный контроль над промптами, памятью, шаблонами Управляемая
Топики Топики Telegram-супергрупп Топики Telegram
Голос Локальный Whisper (опционально) Встроенный

Автор

Разработал Владислав Попов. Пишу об AI-инструментах, автоматизации и рабочих процессах разработки в Telegram-канале — @popovvii.

Лицензия

MIT