A plugin for The Lounge that forwards highlight notifications (nick mentions, highlight words, and private messages) to external services such as Discord, Telegram and Slack.

This plugin leverages The Lounge's built-in highlight detection and provides a per-user configuration saved to The Lounge persistent storage directory.

• Forward highlights to Discord (webhooks), Telegram (bot) and Slack (webhook)
• Per-user settings stored under The Lounge persistent storage dir
• Configure entirely from the client using the /notifier command
• Test notifications from your client

1. Clone or download this repository to your machine:

git clone https://github.com/mhajder/thelounge-plugin-notifier.git

2. Install the plugin into The Lounge:

thelounge install file:./thelounge-plugin-notifier/

3. Restart The Lounge server. Each user must run any /notifier command once after a server restart to ensure their internal client is registered (see Troubleshooting).

Note: The plugin registers a wrapper for the /notifier command which automatically registers the user's internal client when the command is used.

All configuration is done via the /notifier command inside The Lounge. The command accepts several subcommands.

Basic commands

/notifier enable            # Enable notifications for your account
/notifier disable           # Disable notifications for your account
/notifier status            # Show current configuration and enabled/disabled state

Manage channels

/notifier add <type> <args> # Add/configure a notification channel
/notifier remove <type>     # Remove a configured channel
/notifier list              # List configured channels
/notifier test <type>       # Send a test notification to the given channel

Supported channel types and examples

• discord: Webhook URL

  /notifier add discord https://discord.com/api/webhooks/xxxxx/xxxx

• telegram: Bot token and chat id

  /notifier add telegram 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 -987654321

• slack: Webhook URL

  /notifier add slack https://hooks.slack.com/services/...

Examples

• Enable notifications and add a Discord webhook

/notifier enable
/notifier add discord https://discord.com/api/webhooks/xxxxx/xxxx

• Test your configured notification channel

/notifier test discord

The plugin stores notifications per user in separate files:

• <thelounge-home>/packages/thelounge-plugin-notifier/notifications-<username>.json

Each user's notifications are completely isolated from other users. Users can only manage their own notifications.

The Lounge already computes whether a message is a highlight (nickname, configured highlight words, private messages). This plugin listens for messages emitted by the client's internal socket and sends notifications only when the message has the highlight flag set.

Notifications include network, channel, sender and the message text. The plugin also respects channel mute state.

• Users must run a /notifier command at least once after The Lounge server starts so the plugin can register the internal client used to receive 'msg' events. The plugin adds a wrapper to the command which will register the client automatically when the command runs.
• If notifications do not arrive:
  • Ensure the user has highlights configured in The Lounge settings (Settings → Highlights).
  • Make sure the configured webhook URLs / bot tokens / chat IDs are correct.
  • Check that the user's notifications-<userId>.json file exists in The Lounge persistent storage directory and contains the expected channel config.
  • Check The Lounge server logs — this plugin logs using The Lounge logger and will print errors if requests fail.

• Node.js 18.0.0 or higher
• pnpm package manager
• The Lounge 4.3.0 or higher

The project uses Vitest for testing:

# Run all tests
pnpm test

# Run with coverage
pnpm test:coverage

The project uses ESLint and Prettier for code quality:

# Check linting
pnpm lint

# Fix linting issues
pnpm lint:fix

# Check formatting
pnpm format:check

# Format code
pnpm format

This project is licensed under the MIT License - see the LICENSE file for details.