Интеграция с ИИ-агентами
tguser изначально создавался как инструмент для ИИ-агентов (Hermes-Agent, OpenClaw, Claude Code,
Codex CLI и др.): агент вызывает обычную shell-команду и отправляет сообщение в Telegram от имени
пользователя.
Обязательный шаг: глобальная установка
Агент запускает команды из произвольной рабочей директории — того каталога, где идёт его текущая
задача. Вариант uv run tguser … для этого плохо подходит: uv run привязан к проекту, поэтому
из другой директории он определит (и синхронизирует) окружение чужого проекта, в котором
никакого tguser нет. Вызов завершится ошибкой «command not found» — если только tguser уже не
лежит в PATH, а это как раз и даёт глобальная установка.
Поэтому перед интеграцией установите инструмент глобально:
uv tool install git+https://github.com/yerza06/tguser-cli.gitКоманда собирает пакет, создаёт для него изолированное окружение в
~/.local/share/uv/tools/tguser/ и кладёт исполняемый файл в ~/.local/bin/tguser. После этого
агент может вызывать tguser из любой директории — как git или ls. Подробный разбор команды —
в 01. Установка.
Проверить, что всё готово для агента:
cd /tmp && tguser whoami # должен показать текущий аккаунт из любой директорииЧто важно знать агенту
- Команда одна и та же везде —
tguser, без префиксов и безcdв репозиторий. - Состояние глобальное. Учётные данные, сессия и база чатов лежат в
~/.config/tguser/, поэтому результат не зависит от рабочей директории (см. 03. Конфигурация). - Файлы состояния не трогать.
tguser.sessionиtguser.dbв~/.config/tguser/удалять нельзя: первый — авторизация в Telegram, второй — все сохранённые имена чатов. Их удаление ломает агента полностью и требует участия человека (повторный интерактивныйtguser login, ручное восстановление alias) — см. 03. Конфигурация. - Авторизация интерактивна.
tguser loginспрашивает телефон и код — это делает человек один раз. Агенту остаётся только отправка; повторный вход не нужен. - Цель (
--to) лучше задавать именем чата. Человек один раз сохраняет alias (tguser chat add work -1001234567890), а агент использует понятное--to workвместо числового ID (см. 04. Управление чатами). - Коды выхода. Успех —
0, ошибка —1(в том числе ошибки Telegram), прерывание —130. Текст ошибки печатается в stderr, поэтому агент может отличить успешную отправку от неудачной. - Язык вывода. По умолчанию английский;
TGUSER_LANG=ruпереключает сообщения на русский.
Типовые вызовы
tguser send "Задача завершена" --to work
tguser sendfile report.pdf --to work --caption "Отчёт за неделю"
tguser sendphoto chart.png --to meПолный список команд и синтаксис — в 05. Отправка сообщений.
Готовый skill
Чтобы не объяснять агенту устройство tguser каждый раз, установите готовый Agent Skill —
подготовленное описание инструмента (когда его применять, какие команды, где подводные камни),
которое агент подгружает сам, как только задача касается Telegram.
npx skills add https://github.com/yerza06/tguser-cli --skills tguserУстановщик спросит, для каких агентов настроить skill, и скопирует его в их каталог:
| Агент | Куда попадёт skill |
|---|---|
| Claude Code | ~/.claude/skills/tguser/ |
| Codex CLI | ~/.codex/skills/tguser/ |
| Cursor | ~/.cursor/skills/tguser/ |
| OpenCode | ~/.config/opencode/skills/tguser/ |
| OpenClaw | ~/.openclaw/skills/tguser/ |
| Cline, Zed, Warp и другие | ~/.agents/skills/tguser/ |
Skill написан по открытой спецификации Agent Skills,
поэтому работает в любом агенте с её поддержкой — список выше не полный. Исходник лежит в этом
репозитории в skills/tguser/: SKILL.md — краткая инструкция,
references/reference.md — полные таблицы флагов и разбор ошибок.
Skill по-прежнему требует, чтобы человек один раз выполнил tguser login: войти сам он не может
и прямо запрещает агенту это пытаться.