1# CLAUDE.md
 2
 3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 4
 5## Project Overview
 6
 7The 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.
 8
 9## Core Architecture
10
11- **Single executable**: `mumblingherald` - Main Bash script containing all functionality
12- **Configuration**: Variables at the top of the script for paths, recipients, and monitored channels
13- **Dependencies**:
14  - `go-sendxmpp` for XMPP messaging
15  - `tail -F` for log monitoring
16  - Standard Bash utilities
17
18## Key Components
19
20- **Log parsing**: Uses regex to extract user movements and disconnections from Mumble server logs
21- **Message templates**: Arrays of varied join/leave messages with placeholder substitution, embodying a playfully grumpy herald persona
22- **Channel filtering**: Only monitors specific channels defined in `MONITORED_CHANNELS` array
23- **XMPP integration**: Sends notifications via `go-sendxmpp` to configured recipients
24
25## Configuration Variables
26
27Edit these variables in the `mumblingherald` script:
28
29- `MUMBLE_LOG_FILE`: Path to Mumble server log file
30- `XMPP_RECIPIENTS`: Target JID for notifications
31- `MONITORED_CHANNELS`: Array of channel names to watch
32
33## Development Commands
34
35Since this is a single Bash script, there are no build or test commands, just shellcheck.
36
37```bash
38# Make executable
39chmod +x mumblingherald
40
41# Test syntax
42bash -n mumblingherald
43
44# Run shellcheck
45shellcheck mumblingherald
46
47# Run directly
48./mumblingherald
49```
50
51## Deployment
52
53The 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.
54
55## Log Format Parsing
56
57The script parses specific Mumble server log formats. The user session ID, shown as `(SID)` below, can be a negative number (e.g. `(-1)`).
58
59- Move events: `<W>YYYY-MM-DD HH:MM:SS.mmm N => <UID:Username(SID)> Moved Username:UID(SID) to ChannelName[CID:N]`
60- Disconnect events: `<W>YYYY-MM-DD HH:MM:SS.mmm N => <UID:Username(SID)> Connection closed: reason`
61
62## Message Templates
63
64The herald's personality is expressed through varied message templates:
65
66- **Join messages**: Varied announcements ranging from formal to grumbling observations
67- **Leave messages**: Poetic farewells and wistful commentary
68- **Tone**: Playfully grumpy rather than mean-spirited - like a lovably cranky character
69- **Format**: Messages use `{USERNAME}` and `{CHANNEL}` placeholders for substitution
70- **Character actions**: Include physical actions like `*grumbles*`, `*adjusts spectacles*`, `*mutters*`
71
72## Debug Logging
73
74The script includes a `log()` function for debug output when the `DEBUG` environment variable is set to a truthy value (1, true, etc.):
75
76- **Function**: `log()` - Checks `if (($DEBUG))` and prints messages verbatim to stderr
77- **Usage**: Set `DEBUG=1` before running to see herald's internal thoughts
78- **Character**: Debug messages maintain the grumpy herald persona with observations like "_herald squints at parchment_" and "_mutters about modern technology_"
79- **Scope**: Added to helper functions (`is_monitored_channel`, `get_random_message`, `send_notification`, `parse_move_event`, `parse_disconnect_event`) but not main execution flow
80
81Example usage:
82
83```bash
84DEBUG=1 ./mumblingherald
85```
86
87## Development Best Practices
88
89- Use shellcheck after every edit.