Test XMPP Chatbot Connections

XMPP Debugger is a minimal set of Python scripts for exercising an XMPP connection directly: connect as an account, send a single chat message, and listen for replies. It's built around a shared client, scripts/xmpp_client.py, with two entry points on top of it: send_message.py, which sends one message and exits, and listen_messages.py, which listens for incoming messages and prints them as they arrive.

Use it when a task needs to actually poke an XMPP server or bot - sending a test message like "ping" to a contact and confirming a reply comes back, or watching a JID's inbox for a specific sender within a timeout window. It is deliberately minimal: there's no persistent client, roster management, or presence handling, just enough to send and listen for plain chat messages, which makes it a debugging tool rather than a general-purpose XMPP library. The skill is also written with publishing safety in mind - no real JIDs, domains, hostnames, or personal connection points are hardcoded anywhere, and credentials are read only from environment variables, so account/contact details must always be supplied explicitly at runtime.

Setup requires Python 3.10+ with no third-party dependencies (standard library only) and access to a real XMPP server and account. The password is supplied via the XMPP_PASSWORD environment variable; JIDs, targets, and connection details are passed as command-line flags. A typical run looks like:

export XMPP_PASSWORD='...'

python3 scripts/send_message.py \
  --jid user@example.com \
  --to bot@example.com \
  --body 'ping'

python3 scripts/listen_messages.py \
  --jid user@example.com \
  --filter-from bot@example.com \
  --timeout 20

Optional flags cover connection details that vary by server: --host to override the host derived from the JID's domain, --port (default 5222), --resource (default codex), --direct-tls to use direct TLS instead of STARTTLS, and --debug to print the raw XMPP XML to stderr for low-level troubleshooting.

It speaks plain XMPP over TCP, supporting both STARTTLS (the default) and direct TLS, and connects to whatever XMPP server the account's JID domain resolves to (or a host explicitly overridden with --host). Because it has zero external dependencies, it runs anywhere a stock Python 3.10+ interpreter is available.

Developers debugging XMPP-based bots or integrations who need a quick, dependency-free way to send a probe message and watch for the response, including at the raw-XML level when something isn't behaving as expected.