# 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.