Documentation

Notifications

Terminal bells, desktop alerts, and external webhooks — Telegram, Discord, Slack, and custom endpoints.

Edit on GitHub

Nyzhi supports three notification channels: local terminal notifications, desktop notifications, and external webhooks (Telegram, Discord, Slack, or custom URLs).

TUI Notifications

Control how Nyzhi gets your attention in the terminal.

Configuration

[tui.notify]
bell = true           # terminal bell sound
desktop = false       # OS-level desktop notification
min_duration_ms = 5000  # only notify if the turn took longer than this

Slash Commands

Toggle notifications from within the TUI:

/notify                    # show current settings
/notify bell on            # enable terminal bell
/notify bell off           # disable terminal bell
/notify desktop on         # enable desktop notifications
/notify desktop off        # disable desktop notifications
/notify duration 10000     # notify after 10 seconds

Tips

  • Enable desktop for long-running tasks (like test suites or deployments)
  • Set min_duration_ms high enough to avoid noise from quick turns
  • bell works in every terminal; desktop depends on OS notification support

External Notifications

Get notified outside your terminal — on your phone, in a chat room, or via a webhook.

Webhook

Send a JSON payload to any URL:

[external_notify]
webhook_url = "https://hooks.example.com/nyzhi"

The payload includes session info, event type, and message content.

Telegram

[external_notify]
telegram_bot_token = "123456:ABC-DEF..."
telegram_chat_id = "987654321"

To set up:

  1. Create a bot with BotFather
  2. Get the bot token
  3. Send a message to the bot, then get your chat ID from the API

Discord

[external_notify]
discord_webhook_url = "https://discord.com/api/webhooks/..."

Create a webhook in your Discord server settings under Integrations.

Slack

[external_notify]
slack_webhook_url = "https://hooks.slack.com/services/T.../B.../..."

Create an incoming webhook in your Slack workspace.

Team Idle Notifications

In team workflows, when a teammate finishes a turn and has no pending work, an idle notification is sent to the team lead’s inbox. This is internal messaging, not a desktop or webhook notification.

The team lead can pick up idle notifications with:

read_inbox()

See Teams for more on team communication.

Security

  • Store webhook credentials in config.local.toml or environment variables — never in a committed config file
  • Add config.local.toml to .gitignore
  • Webhook URLs are secrets — treat them accordingly

Next Steps

  • Configuration — notification config reference
  • Teams — team communication and inbox
  • Hooks — trigger actions on events
Back to overview