Stefano Fiorini
162 lines
4.4 KiB
Markdown
162 lines
4.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](./PI-COMMON-REVIEWER.md) for full details.
|
|
|
|
Global install:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
export TELEGRAM_BOT_TOKEN="<bot-token>"
|
|
export TELEGRAM_CHAT_ID="<chat-id>"
|
|
```
|
|
|
|
Optional:
|
|
|
|
```bash
|
|
export TELEGRAM_API_BASE_URL="https://api.telegram.org"
|
|
```
|
|
|
|
## Test the Helper
|
|
|
|
Non-Pi agents example:
|
|
|
|
```bash
|
|
TELEGRAM_BOT_TOKEN="<bot-token>" \
|
|
TELEGRAM_CHAT_ID="<chat-id>" \
|
|
skills/reviewer-runtime/notify-telegram.sh --message "Telegram notification test"
|
|
```
|
|
|
|
Pi example:
|
|
|
|
```bash
|
|
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.
|