thelounge-plugin-highlightmon

A plugin for TheLounge that creates a highlight monitor to stream all highlighted messages in real-time.

Features

• Real-time highlight monitoring: Creates a highlightmon local buffer that displays all messages that would trigger highlights
• Channel prefixes: Each message is prefixed with the originating channel name for easy identification
• Toggle control: Use /highlightmon command to enable/disable monitoring
• Smart highlight detection: Uses TheLounge's built-in highlight settings (keywords and nick mentions)
• Exception support: Respects TheLounge's highlight exceptions to avoid false positives
• Action support: Monitors both regular messages and IRC actions that contain highlights
• Per-network: Each IRC network gets its own highlightmon buffer
• Command-based: Use /highlightmon to create and toggle monitoring

Installation

Via npm (when published)

thelounge install thelounge-plugin-highlightmon

Manual installation (current method)

1. Clone this repository:

   git clone https://github.com/jjasghar/thelounge-plugin-highlightmon.git

2. Install in your TheLounge packages directory:

   cd ~/.thelounge/packages
   npm install file:path/to/thelounge-plugin-highlightmon

3. Restart TheLounge:

   thelounge restart

4. The plugin will be loaded automatically and ready to use with /highlightmon

Usage

Basic Usage

Once installed, use the /highlightmon command to:

1. Create a highlightmon local buffer on the current IRC network
2. Toggle monitoring of highlighted messages in real-time
3. Display messages in the format: [#channel] <nick> message
4. Mark messages as highlighted so they appear with highlight styling

Commands

• /highlightmon - Toggle highlight monitoring on/off for the current network

Example Output

[#thelounge] <alice> jjasghar: how's the new project going?
[#development] <bob> The urgent bug needs attention from jjasghar  
[#general] <charlie> @jjasghar the deployment is ready for review
[#random] <dave> kubernetes cluster is down - need help!

Note: Only messages containing your nickname or configured highlight keywords will appear, unlike chanmon which shows all messages.

Highlight Detection

The plugin uses TheLounge's built-in highlight system and will monitor messages that contain:

Automatic Highlights

• Your nickname: Any mention of your current IRC nickname
• Configured keywords: Keywords you've set in TheLounge's highlight settings

Highlight Settings

You can configure highlights in TheLounge's settings:

1. Go to Settings → Highlights
2. Add keywords you want to monitor
3. Add exceptions for words that should not trigger highlights
4. The plugin will automatically use these settings

What gets monitored

Monitored:

• Regular channel messages containing highlights
• IRC actions (/me commands) containing highlights
• Messages matching your configured highlight keywords
• Messages mentioning your nickname

Not monitored:

• Join/part/quit messages
• Nick changes
• Mode changes
• Topic changes
• Messages from the highlightmon buffer itself (prevents loops)
• Private messages (use TheLounge's built-in highlight system for PMs)
• Messages matching highlight exceptions

Configuration

The plugin works out of the box with no additional configuration required. It will:

• Create the highlightmon buffer when you run /highlightmon
• Use your existing TheLounge highlight settings
• Start streaming highlighted messages when enabled

Compatibility

• TheLounge version: 4.0.0 or higher
• Node.js version: 14.0.0 or higher

How it differs from chanmon

While thelounge-plugin-chanmon shows ALL channel activity, highlightmon is laser-focused and only shows:

• Highlight-triggered messages only: Messages that would normally trigger TheLounge's highlight notifications
• Nickname mentions: Any message containing your current IRC nickname
• Custom keywords: Messages containing keywords you've configured in TheLounge's highlight settings
• Noise reduction: Dramatically reduces message volume compared to chanmon
• Smart filtering: Respects your highlight exceptions to avoid false positives

This makes it perfect for monitoring important mentions across multiple busy channels without getting overwhelmed by general chatter.

Real-world example:

• chanmon: Shows 500+ messages per hour from all channels
• highlightmon: Shows only the 5-10 messages that actually mention you or your keywords

Development

To contribute to this plugin:

1. Fork the repository
2. Make your changes
3. Test with a local TheLounge installation
4. Submit a pull request

Testing

1. Install the plugin in your TheLounge installation
2. Connect to an IRC network
3. Run /highlightmon in any channel to create the buffer and enable monitoring
4. Configure highlight keywords in Settings → Highlights (optional)
5. Test highlight detection:
   • Have someone mention your nickname: yournick: hello there
   • Use a configured keyword in a message
   • Check that messages appear in the highlightmon buffer
6. Run /highlightmon again to toggle monitoring off/on
7. Verify the plugin works alongside other plugins like chanmon

Verified Working On

• ✅ TheLounge v4.4.3
• ✅ Node.js 23.11.0
• ✅ macOS (darwin arm64)
• ✅ Works alongside thelounge-plugin-chanmon

License

MIT License - see LICENSE file for details.

Support

If you encounter any issues or have feature requests, please open an issue on the GitHub repository.

Related Plugins

• thelounge-plugin-chanmon - Monitor all channel activity
• thelounge-plugin-closepms - Close all open PMs on a network
• thelounge-plugin-autodownload - Autodownload torrents in qBittorrent