ai-coding-skills/docs/TELEGRAM-NOTIFICATIONS.md

TELEGRAM-NOTIFICATIONS

Purpose

Shared setup for Telegram notifications used by reviewer-driven skills such as create-plan, implement-plan, and do-task, both for completion and for pauses that need user attention.

Requirements

• Telegram bot token in TELEGRAM_BOT_TOKEN
• Telegram chat id in TELEGRAM_CHAT_ID
• Notification helper installed beside the shared reviewer runtime:
  • Codex: ~/.codex/skills/reviewer-runtime/notify-telegram.sh
  • Claude Code: ~/.claude/skills/reviewer-runtime/notify-telegram.sh
  • OpenCode: ~/.config/opencode/skills/reviewer-runtime/notify-telegram.sh
  • Cursor: .cursor/skills/reviewer-runtime/notify-telegram.sh or ~/.cursor/skills/reviewer-runtime/notify-telegram.sh
  • Pi: .pi/skills/reviewer-runtime/pi/notify-telegram.sh or ~/.pi/agent/skills/reviewer-runtime/pi/notify-telegram.sh

Install

The helpers ship from skills/reviewer-runtime/ (non-Pi) and skills/reviewer-runtime/pi/ (Pi) together with run-review.sh.

Codex

mkdir -p ~/.codex/skills/reviewer-runtime
cp skills/reviewer-runtime/run-review.sh \
   skills/reviewer-runtime/notify-telegram.sh \
   ~/.codex/skills/reviewer-runtime/
chmod +x ~/.codex/skills/reviewer-runtime/*.sh

Claude Code

mkdir -p ~/.claude/skills/reviewer-runtime
cp skills/reviewer-runtime/run-review.sh \
   skills/reviewer-runtime/notify-telegram.sh \
   ~/.claude/skills/reviewer-runtime/
chmod +x ~/.claude/skills/reviewer-runtime/*.sh

OpenCode

mkdir -p ~/.config/opencode/skills/reviewer-runtime
cp skills/reviewer-runtime/run-review.sh \
   skills/reviewer-runtime/notify-telegram.sh \
   ~/.config/opencode/skills/reviewer-runtime/
chmod +x ~/.config/opencode/skills/reviewer-runtime/*.sh

Cursor

Repo-local install:

mkdir -p .cursor/skills/reviewer-runtime
cp skills/reviewer-runtime/run-review.sh \
   skills/reviewer-runtime/notify-telegram.sh \
   .cursor/skills/reviewer-runtime/
chmod +x .cursor/skills/reviewer-runtime/*.sh

Global install:

mkdir -p ~/.cursor/skills/reviewer-runtime
cp skills/reviewer-runtime/run-review.sh \
   skills/reviewer-runtime/notify-telegram.sh \
   ~/.cursor/skills/reviewer-runtime/
chmod +x ~/.cursor/skills/reviewer-runtime/*.sh

Pi

Pi uses a separate set of helpers from skills/reviewer-runtime/pi/ that are optimized for the Pi agent environment. See PI-COMMON-REVIEWER.md for full details.

Global install:

mkdir -p ~/.pi/agent/skills/reviewer-runtime/pi
cp -R skills/reviewer-runtime/pi/* ~/.pi/agent/skills/reviewer-runtime/pi/
chmod +x ~/.pi/agent/skills/reviewer-runtime/pi/*.sh

Repo-local install:

mkdir -p .pi/skills/reviewer-runtime/pi
cp -R skills/reviewer-runtime/pi/* .pi/skills/reviewer-runtime/pi/
chmod +x .pi/skills/reviewer-runtime/pi/*.sh

Verify Installation

Verify: Non-Pi agents

test -x ~/.codex/skills/reviewer-runtime/notify-telegram.sh || true
test -x ~/.claude/skills/reviewer-runtime/notify-telegram.sh || true
test -x ~/.config/opencode/skills/reviewer-runtime/notify-telegram.sh || true
test -x .cursor/skills/reviewer-runtime/notify-telegram.sh \
  || test -x ~/.cursor/skills/reviewer-runtime/notify-telegram.sh || true

Verify: Pi

test -x .pi/skills/reviewer-runtime/pi/notify-telegram.sh \
  || test -x ~/.pi/agent/skills/reviewer-runtime/pi/notify-telegram.sh || true

Configure Telegram

Export the required variables before running a skill that sends Telegram notifications:

export TELEGRAM_BOT_TOKEN="<bot-token>"
export TELEGRAM_CHAT_ID="<chat-id>"

Optional:

export TELEGRAM_API_BASE_URL="https://api.telegram.org"

Test the Helper

Non-Pi agents example:

TELEGRAM_BOT_TOKEN="<bot-token>" \
TELEGRAM_CHAT_ID="<chat-id>" \
skills/reviewer-runtime/notify-telegram.sh --message "Telegram notification test"

Pi example:

TELEGRAM_BOT_TOKEN="<bot-token>" \
TELEGRAM_CHAT_ID="<chat-id>" \
skills/reviewer-runtime/pi/notify-telegram.sh --message "Pi Telegram test"

Rules

• Telegram is the only supported notification path for these skills.
• Notification failures are non-blocking, but they must be surfaced to the user.
• Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
• Skills should report when Telegram is not configured instead of silently pretending a notification was sent.