Notifications

RalphTerm fires notifications on plan completion, plan failure, repeated review failure, and detected rate-limit pauses. Channels match ralphex: Telegram, Slack, Email (SMTP), and a generic Webhook. Each delivery has a 10s timeout and never blocks the run.

Configure under [notify]

Configuration lives in ~/.config/ralphex/config.json (or .ralphex/config.json for project overrides):

{
  "notify": {
    "telegram_token": "123456:ABC...",
    "telegram_chat_id": "987654321",
    "slack_webhook": "https://hooks.slack.com/services/T.../B.../...",
    "email_smtp": "smtp.example.com:587",
    "email_to": "ops@example.com",
    "webhook_url": "https://ci.example.com/hooks/ralphterm",
    "notify_on": "plan_done,task_failed,review_failed,rate_limit"
  }
}

Create a Telegram bot via @BotFather to get the bot token, then send any message to it to obtain a chat id. RalphTerm posts plain-text messages via sendMessage.

# CLI override
ralphterm --notify-telegram-token "$TG_TOKEN" \
          --notify-telegram-chat "$TG_CHAT" \
          --notify-on plan_done,review_failed \
          docs/plans/feature.md

Slack

Configure an Incoming Webhook in your Slack workspace and paste the URL into slack_webhook. Messages are posted as JSON with a short status line.

# CLI override
ralphterm --notify-slack "$SLACK_WEBHOOK" docs/plans/feature.md

Email (SMTP)

RalphTerm sends plain-text email via SMTP. Configure email_smtp with host:port and email_to with the recipient. Credentials are read from the environment (SMTP_USER, SMTP_PASS).

export SMTP_USER=alerts@example.com
export SMTP_PASS=...
ralphterm docs/plans/feature.md

Webhook

Generic POST with a JSON body. Useful for CI, paging, and custom dashboards.

# Payload shape
{
  "event": "review_failed",
  "plan": "docs/plans/feature.md",
  "task": "Implement smoke output",
  "iteration": 2,
  "transcript_url": "https://ralphterm.local/v1/runs/.../progress/review.txt"
}

Security notes

Always prefer HTTPS endpoints for Slack and Webhook delivery. RalphTerm enforces TLS by default and refuses to send notifications over plain HTTP. The override env var RALPHTERM_NOTIFY_ALLOW_INSECURE=1 lifts that check; use it only for local testing.

Tokens and webhook URLs are secrets. Keep them in ~/.config/ralphex/config.json (mode 0600) or supply them via environment variables and CLI overrides at run time rather than committing them to a project repo.