# tg-agent

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

Агент не только читает переписку, но и **смотрит** картинки (`tg_view` отдаёт само
изображение) и **слушает** звук: голосовые, кружки, музыка и видео расшифровываются
в текст встроенной расшифровкой Telegram, через Groq Whisper или локальной моделью.
Длинные посты пересказывает сам Telegram (`tg_summarize`), сторис читаются, не
оставляя следа, а `tg_wait` и `tg_ask` дают агенту дождаться нужного сообщения
или спросить разрешения у владельца прямо в боте.

Работает поверх MTProto (Telethon), а не Bot API — поэтому видно весь аккаунт,
а не только сообщения, написанные боту.

## Что внутри

```
MCP-клиент (Claude Code, Claude Desktop, любой другой)
        │  stdio
        ▼
tgagent.mcp_server ──unix socket──▶ tgagent.daemon ──MTProto──▶ Telegram
   70 инструментов     /data/daemon.sock    │
                                             ├─ watcher: входящие → правила → алерт
                                             └─ Bot API ──▶ твой бот ──▶ ты
```

Ядро — `tgagent/core.py`: один класс `TelegramService`, все операции с аккаунтом
и все предохранители. Всё остальное — транспорт вокруг него. Подробнее:
[docs/architecture.md](docs/architecture.md).

## Быстрый старт (локально)

```bash
git clone <repo> ~/tg-agent && cd ~/tg-agent
cp .env.example .env && chmod 600 .env

uv sync
uv run tg setup     # api_id/api_hash с my.telegram.org + токен бота
uv run tg login     # телефон, код, при 2FA — облачный пароль
uv run tg daemon start
uv run tg status
```

Подключение к Claude Code:

```bash
claude mcp add telegram -- uv --directory ~/tg-agent run tg-mcp
```

Дальше — [docs/mcp.md](docs/mcp.md): область видимости, Claude Desktop, готовые
субагенты, проверка что всё поднялось.

## Быстрый старт (docker)

```bash
cp .env.example .env && chmod 600 .env   # заполни TG_API_ID / TG_API_HASH / TG_BOT_TOKEN
docker compose build
docker compose run --rm tgagent tg login # логин интерактивно, сессия ляжет в ./data
docker compose up -d
```

MCP-клиент подключается к тому же контейнеру:

```bash
claude mcp add telegram -- docker exec -i tgagent tg-mcp
```

Подробности, включая почему MCP запускается внутри контейнера, а не на хосте —
[docs/docker.md](docs/docker.md).

## Документация

| Файл | О чём |
|---|---|
| [docs/architecture.md](docs/architecture.md) | ядро, слои, инварианты, поток данных, что где лежит |
| [docs/tools.md](docs/tools.md) | справочник всех 70 MCP-инструментов с параметрами |
| [docs/configuration.md](docs/configuration.md) | переменные окружения, правила алертов, лимиты, файлы состояния |
| [docs/mcp.md](docs/mcp.md) | подключение как MCP-сервер, субагенты, диагностика |
| [docs/docker.md](docs/docker.md) | сборка, логин в контейнере, обновление, бэкап |
| [docs/security.md](docs/security.md) | модель угроз: что защищено, что нет, как отозвать доступ |

## Команды

```bash
uv run tg status                      # что настроено, что нет, состояние демона
uv run tg setup                       # ключи и токен бота
uv run tg login                       # вход целиком
uv run tg send-code +7XXXXXXXXXX      # то же в три шага, без интерактива
uv run tg sign-in --code 12345
uv run tg password                    # облачный пароль 2FA, только с живого tty
uv run tg link-bot                    # привязать chat_id для алертов
uv run tg accounts                    # какие аккаунты залогинены
uv sync --extra local-whisper         # локальная расшифровка звука (опционально)
uv run tg login --account work        # добавить второй аккаунт
uv run tg daemon start|run|stop|restart|logs
uv run tg call dialogs '{"limit": 5}' # дёрнуть метод демона мимо MCP
uv run tg logout                      # отозвать сессию и стереть файлы
```

## Предохранители

- 60 сообщений в час, максимум 15 разных чатов в час (анти-рассылка), 50 удалений в час
- `TG_ALLOW_WRITE=0` полностью выключает запись
- каждое пишущее действие пишется в `data/actions.jsonl`
- неоднозначное имя чата не угадывается: инструмент возвращает список кандидатов
- FloodWait от Telegram возвращается понятной ошибкой, а не падением
- содержимое чужих сообщений в промптах субагентов объявлено данными, а не командами