mqtt-monitor-topic

name	mqtt-monitor-topic
description	Subscribe to a specific MQTT topic or topic pattern (e.g. `zigbee2mqtt/#`, `home/livingroom/+/state`) on the configured broker and stream matching payloads. Use when the user wants to watch a single device, namespace, or subtree rather than all broker traffic. Requires `/mqtt-setup` to have been run previously.

Monitor a specific MQTT topic / space

Subscribe to a user-specified topic filter and stream matching payloads.

Get the topic filter

Ask the user for the topic pattern if not already given. Accept MQTT wildcards:

• + — single-level wildcard
• # — multi-level wildcard (must be at the end)

Examples:

• zigbee2mqtt/# — all Zigbee2MQTT traffic
• home/livingroom/+/state — state topic for any device in the livingroom namespace
• homeassistant/sensor/+/config — HA discovery configs for sensors

Load credentials

if [ ! -f ~/.claude/plugins-data/mqtt-observability/credentials.env ]; then
  echo "No MQTT credentials found. Run /mqtt-setup first." >&2
  exit 1
fi
set -a; . ~/.claude/plugins-data/mqtt-observability/credentials.env; set +a

Subscribe

mosquitto_sub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  ${MQTT_USERNAME:+-u "$MQTT_USERNAME"} \
  ${MQTT_PASSWORD:+-P "$MQTT_PASSWORD"} \
  -t "<user-supplied-topic-filter>" -v

Run strategy

• For bounded capture: timeout <N> mosquitto_sub ... (ask the user how long; default 30s).
• For open-ended observation: run_in_background: true, then use Monitor to stream events. Stop the job when the user says so.

Output

Report:

• Topic filter used
• Number of messages received
• Distinct full topics that matched
• Pretty-printed JSON payloads where applicable

Dependency

mosquitto-clients (sudo apt install mosquitto-clients).