CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

The Mumbling Herald is a Bash script that monitors Mumble server logs and sends XMPP notifications when users join or leave specified channels. It acts as a "grumpy old herald" that announces comings and goings.

Core Architecture

  • Single executable: mumblingherald - Main Bash script containing all functionality
  • Configuration: Variables at the top of the script for paths, recipients, and monitored channels
  • Dependencies:
    • go-sendxmpp for XMPP messaging
    • tail -F for log monitoring
    • Standard Bash utilities

Key Components

  • Log parsing: Uses regex to extract user movements and disconnections from Mumble server logs
  • Message templates: Arrays of varied join/leave messages with placeholder substitution, embodying a playfully grumpy herald persona
  • Channel filtering: Only monitors specific channels defined in MONITORED_CHANNELS array
  • XMPP integration: Sends notifications via go-sendxmpp to configured recipients

Configuration Variables

Edit these variables in the mumblingherald script:

  • MUMBLE_LOG_FILE: Path to Mumble server log file
  • XMPP_RECIPIENTS: Target JID for notifications
  • MONITORED_CHANNELS: Array of channel names to watch

Development Commands

Since this is a single Bash script, there are no build or test commands, just shellcheck.

# Make executable
chmod +x mumblingherald

# Test syntax
bash -n mumblingherald

# Run shellcheck
shellcheck mumblingherald

# Run directly
./mumblingherald

Deployment

The script is designed to run as a systemd service under a dedicated user account. See README.md for full setup instructions including user creation, file permissions, and systemd service configuration.

Log Format Parsing

The script parses specific Mumble server log formats. The user session ID, shown as (SID) below, can be a negative number (e.g. (-1)).

  • Move events: <W>YYYY-MM-DD HH:MM:SS.mmm N => <UID:Username(SID)> Moved Username:UID(SID) to ChannelName[CID:N]
  • Disconnect events: <W>YYYY-MM-DD HH:MM:SS.mmm N => <UID:Username(SID)> Connection closed: reason

Message Templates

The herald's personality is expressed through varied message templates:

  • Join messages: Varied announcements ranging from formal to grumbling observations
  • Leave messages: Poetic farewells and wistful commentary
  • Tone: Playfully grumpy rather than mean-spirited - like a lovably cranky character
  • Format: Messages use {USERNAME} and {CHANNEL} placeholders for substitution
  • Character actions: Include physical actions like *grumbles*, *adjusts spectacles*, *mutters*

Debug Logging

The script includes a log() function for debug output when the DEBUG environment variable is set to a truthy value (1, true, etc.):

  • Function: log() - Checks if (($DEBUG)) and prints messages verbatim to stderr
  • Usage: Set DEBUG=1 before running to see herald's internal thoughts
  • Character: Debug messages maintain the grumpy herald persona with observations like "herald squints at parchment" and "mutters about modern technology"
  • Scope: Added to helper functions (is_monitored_channel, get_random_message, send_notification, parse_move_event, parse_disconnect_event) but not main execution flow

Example usage:

DEBUG=1 ./mumblingherald

Development Best Practices

  • Use shellcheck after every edit.