setup

Files (1)

• SKILL.md

SKILL.md (first lines)

# Telegram Notify — guided setup

You are configuring Telegram notifications that ping the user when a Claude Code
session needs a human (questions, permission prompts, idle after finishing, API-error
stalls). The per-user config lives at `~/.claude/telegram-notify.env`. Do the steps in
order, one at a time, and wait for the user's reply wherever input is needed. Use only
`curl`, `Read`, `Write`, and `Bash` — everything below works in terminal and VS Code
extension sessions alike.

## 0. Check the current state

Read `~/.claude/telegram-notify.env`. If it exists with a non-empty token and chat id,
run the test in step 5 first — if it succeeds, tell the user notifications already
work, ask whether they want to reconfigure, and stop unless they say yes.

## 1. Bot token

Ask the user to open Telegram, message **@BotFather**, send `/newbot`, follow the two
prompts (bot name, bot username), and paste the resulting token here.

State this caveat in one sentence, without drama: the token they paste becomes part
of this chat's locally stored transcript; if they'd rather keep it out of the chat,
they can instead write it to `~/.claude/telegram-notify.env` themselves (README
"Config reference") and skip to step 5.

When you receive the token: it must match `digits:alphanumeric` (e.g.
`1234567890:AAF3xy...`). Strip whitespace. Validate it live:

```bash
curl -s "https://api.telegram.org/bot<TOKEN>/getMe"
```

`"ok":true` → proceed. 401/404 → the token is wrong; ask them to re-copy it from
BotFather.

## 2. Chat id — detect it automatically

Ask the user to send any message (e.g. "hi") **to their new bot** — bots cannot
message a person first. Once they confirm, fetch:

```bash
curl -s "https://api.telegram.org/bot<TOKEN>/getUpdates"
```

Take `result[-1].message.chat.id` (the most recent update). If `result` is empty,
they haven't messaged the bot yet (or messaged the wrong bot) — ask again and retry.
Do not ask the user to find their chat id manually unless getUpdates fails twice.

## 3. Write the config

Write `~/.claude/telegram-notify.env` (create or overwrite after confirming, if one
already existed):

```bash
TELEGRAM_BOT_TOKEN="<token>"
TELEGRAM_CHAT_ID="<chat id>"
NOTIFY_WHEN="manual"
AWAY_IDLE_SECONDS=120
DEBOUNCE_SECONDS=30
DRY_RUN=0
```

Then `chmod 600 ~/.claude/telegram-notify.env`.

## 4. Explain the on/off switch (three sentences), then offer the hotkey

Pings are off by default while they work; when leaving the computer they run
`/telegram-notify:enable` in any chat (and `/telegram-notify:disable` when back —
`/telegram-notify:status` to check), or use `toggle-away.sh on|off`. Toggling is
checked at event time, so it never interrupts a running task. Users who prefer
automatic behavior can set `NOTIFY_WHEN="auto"` (system-idle detection) in the
config.

Then OFFER to install a VS Code toggle hotkey (`⌘⌥N` / `ctrl+alt+n`). If accepted:
add a shell task labeled "Toggle Claude pings" to the user-level `tasks.json` and a
keybinding running it to `keybindings.json` (macOS: `~/Library/Application
Support/Code/User/`; Linux: `~/.config/Code/User/`). The task flips
`~/.claude/notify-on` (also clearing `notify-off` when enabling) and shows feedback
(macOS `osascript display notification`, else echo). **Merge, don't overwrite**: if
either file exists, Read it first and append to the existing arrays; VS Code allows
comments in these files, so if JSON parsing fails, edit the text carefully instead.
If the user picks a different key, check it's not a common default binding.

## 5. Test

Send a real test message:

```bash
curl -s "https://api.telegram.org/bot<TOKEN>/sendMessage" \
  --data-urlencode "chat_id=<chat id>" \
  --data-urlencode "text=🔔 Test from claude-telegram-notify — your Claude Code sessions will ping this chat when they need you."
```

`"ok":true` → ask the user to confirm the message arrived in Telegram. Anything else
→ show them the API response and fix the cause (usually a wrong token or chat id)
before continuing.

## 6. Restart

Tell the user hooks load at session start, so running sessions won't ping yet:

- **VS Code**: Command Palette → "Developer: Reload Window" (restarts the extension
  and its sessions).
- **Terminal**: exit and restart `claude` in each open session.

Close by summarizing what will now ping them and when, in three lines or fewer.

From arturdev/claude-telegram-notify, MIT.

More from arturdev/claude-telegram-notify