# Telegram Hook Fix

> Two Claude Code hooks that fix the most common Telegram plugin failures — stale bot processes holding the bot token (409 Conflict on next session) and silently dropped replies (agent forgets to call the reply tool). Triggers on "telegram hook fix", "telegram 409", "telegram bot conflict", "telegram reply guard", "fix telegram plugin".

- Skill: `robonuggets/telegram-hook-fix` (Agent Skill)
- Install (CLI): `npx skillmds@latest add robonuggets/telegram-hook-fix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/robonuggets/telegram-hook-fix/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: robonuggets (https://skillmd.com/u/robonuggets)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/robonuggets/telegram-hook-fix

---


# Telegram Hook Fix

Two local hooks for the official Claude Code Telegram plugin. Both run as deterministic Python — zero Claude tokens, zero model inference.

## What it fixes

**1. SessionStart · Telegram Cleanup** (`telegram-preemptive-kill.py`)

Telegram allows exactly one `getUpdates` consumer per bot token. On Windows the plugin's clean-shutdown path is unreliable — when a terminal is X'd out, the machine sleeps, or a session crashes hard, the bot subprocess can linger and hold the token. The next session then fails with `409 Conflict`.

This hook runs just before MCP servers spin up. It reads the plugin's `bot.pid` file, force-kills that PID, and removes the pid file so the plugin starts fresh.

**2. Stop · Reply Guard** (`telegram-reply-guard.py`)

If the last Telegram inbound this turn didn't get a reply tool call, this hook sends a fallback message to the same chat so the user isn't left hanging. Hits Telegram's Bot API directly via urllib.

## Installation

1. Copy both `hooks/*.py` files into a stable location on your machine (e.g. `~/.claude/hooks/` or anywhere else outside the project tree).
2. Merge the snippet from `settings.example.json` into your Claude Code settings (`~/.claude/settings.json`) — adjusting the absolute path to where you placed the scripts.
3. Restart Claude Code. New sessions will run the SessionStart hook before the Telegram plugin starts; the Stop hook fires at the end of every turn.

## How to apply

When the user asks "install the telegram hook fix" or pastes a clone URL for this repo:

1. Read the `README.md` for the install steps.
2. Confirm where the user wants the scripts installed (default suggestion: `~/.claude/hooks/`).
3. Copy `hooks/telegram-preemptive-kill.py` and `hooks/telegram-reply-guard.py` to that location.
4. Read the user's existing `~/.claude/settings.json`. Merge the `hooks` block from `settings.example.json` — preserve any existing hooks, do not overwrite. Update the script paths to match where you placed the files.
5. Tell the user what changed and where, then ask them to restart Claude Code.

## Troubleshooting

- **Hook doesn't fire:** Confirm Python is on PATH (`python --version`). On Windows, `python` should resolve. If not, swap `python` for the absolute path to your interpreter inside `settings.json`.
- **Reply Guard never sends:** It needs the bot token. The script looks at `$TELEGRAM_BOT_TOKEN` first, then falls back to `<channel_state_dir>/.env`. If neither has it, no fallback is sent (failure is silent — check the `reply-guard.log` file inside the channel state dir).
- **Kill hook runs but plugin still 409s:** The plugin may have already grabbed the token before the hook ran. Kill the process manually once (`taskkill /F /PID <pid>` on Windows), then start a fresh session.

## License

CC BY 4.0 — free to use with attribution.