AI Agent Integration
tguser was built for AI agents (Hermes-Agent, OpenClaw, Claude Code, Codex CLI, etc.) from the
start: the agent runs a plain shell command and a Telegram message goes out from your user account.
Required step: install globally
An agent runs commands from an arbitrary working directory — whichever project it is currently
working on. uv run tguser … is a poor fit for that: uv run is tied to a project, so from another
directory it resolves (and syncs) that project’s environment, which has no tguser in it. The
call then fails with “command not found” — unless tguser is already on PATH, which is exactly
what a global install gives you.
So install the tool globally before wiring up any agent:
uv tool install git+https://github.com/yerza06/tguser-cli.gitThe command builds the package, creates an isolated environment for it under
~/.local/share/uv/tools/tguser/, and places the executable at ~/.local/bin/tguser. From then on
the agent can call tguser from any directory, just like git or ls. See
01. Installation for a breakdown of what the command does.
To confirm the setup is agent-ready:
cd /tmp && tguser whoami # should show the current account from any directoryWhat the agent needs to know
- The command is the same everywhere —
tguser, with no prefix and nocdinto the repository. - State is global. Credentials, the session, and the chat database live in
~/.config/tguser/, so the result does not depend on the working directory (see 03. Configuration). - Leave the state files alone.
tguser.sessionandtguser.dbin~/.config/tguser/must never be deleted: the first one is your Telegram authorization, the second holds every saved chat name. Deleting them breaks the agent completely and requires a human (another interactivetguser login, rebuilding the aliases by hand) — see 03. Configuration. - Signing in is interactive.
tguser loginasks for a phone number and a code — a human does that once. The agent only sends; no repeated login is needed. - Prefer chat aliases for
--to. A human saves the alias once (tguser chat add work -1001234567890) and the agent uses the readable--to workinstead of a numeric ID (see 04. Chat Management). - Exit codes.
0on success,1on failure (including Telegram errors),130on interrupt. The error text goes to stderr, so an agent can tell a successful send from a failed one. - Output language. English by default;
TGUSER_LANG=ruswitches messages to Russian.
Typical calls
tguser send "Task finished" --to work
tguser sendfile report.pdf --to work --caption "Weekly report"
tguser sendphoto chart.png --to meFor the full command list and syntax, see 05. Sending Messages.
Ready-made skill
Instead of explaining tguser to your agent every time, install the bundled Agent Skill — a
prepared description of the tool (when to use it, the commands, the pitfalls) that the agent loads
by itself as soon as a task involves Telegram.
npx skills add https://github.com/yerza06/tguser-cli --skills tguserThe installer asks which agents to set it up for and copies the skill into their skill directory:
| Agent | Where the skill lands |
|---|---|
| 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 and others | ~/.agents/skills/tguser/ |
The skill follows the open Agent Skills specification, so
it works in any agent that supports the standard — the list above is not exhaustive. The source
lives in this repository at skills/tguser/: SKILL.md holds the
short instructions, references/reference.md the full flag tables and troubleshooting.
The skill still needs a human to run tguser login once — it cannot sign in on its own, and it
explicitly instructs the agent not to try.