XMPP Debugger

Install

Use the scripts from https://github.com/maxeetig/xmpp-debugger-skill: take the password from XMPP_PASSWORD, send via scripts/send_message.py and listen with scripts/listen_messages.py.

This is third-party code. Review the repository files before installing.

What it does

The skill gives the agent two scripts: send_message.py logs in and sends one message, and listen_messages.py listens for incoming messages from a given contact until a timeout. Shared client logic lives in xmpp_client.py and uses only the Python standard library. The password comes from the XMPP_PASSWORD variable, and sender and recipient JIDs are passed explicitly at runtime.

Who it is for. Developers and testers of chatbots running over XMPP.

Example request

Send ping to bot@example.com from user@example.com and show what it replies within 20 seconds

Limitations

Only sending a single message and listening for replies are supported. It needs access to an XMPP server and a valid account. If the host differs from the JID domain, pass it with --host.

How to disable. Delete the skill folder from the agent's skills directory and unset XMPP_PASSWORD.

Security check

• Uses an XMPP account password from the environment
• Opens network connections to the server

README in short

The repository holds minimal Python scripts for XMPP debugging: connecting, sending a message and listening for replies. No real JIDs or server addresses are hardcoded, and credentials are read only from environment variables. It needs Python 3.10+ and access to an XMPP server. The README lists the scripts and optional flags.

SKILL.md

---
name: xmpp-debugger
description: Send and receive XMPP chat messages for bot debugging and manual protocol checks. Use when Codex needs to talk to an XMPP contact, inspect replies, and verify chatbot behavior over XMPP.
---

# Xmpp Debugger

## Overview

Use the bundled scripts to authenticate with your configured account, send a chat message, and wait for incoming replies from a bot or another contact. Prefer the scripts over handwritten socket code so the login and stanza flow stay consistent.

## Workflow

1. Export the password without writing it to disk:

```bash
export XMPP_PASSWORD='...'
```

2. Send a message to the bot or another contact:

```bash
python3 scripts/send_message.py \
  --jid user@example.com \
  --to bot@example.com \
  --body 'hello from codex'
```

3. Listen for replies:

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

4. If the server uses a different host than the JID domain, read [xmpp-notes.md](references/xmpp-notes.md) and pass `--host`.

## Defaults

- Sender JID: required (`--jid`)
- Peer JID: required for send (`--to`) and optional filter for listen (`--filter-from`)
- Password source: `XMPP_PASSWORD`
- Default port: `5222`
- Default resource: `codex`

Override these values with flags only when the environment differs from the standard setup.

## Scripts

- `scripts/send_message.py`: Log in, bind a resource, send one chat message, and exit.
- `scripts/listen_messages.py`: Log in, announce presence, and print matching incoming chat messages until timeout.
- `scripts/xmpp_client.py`: Shared minimal XMPP client implementation.

## Operating Rules

- Keep credentials in environment variables, not in prompts or files.
- Use the send script for deterministic outbound tests instead of composing raw XML by hand.
- Use the listen script when you need the bot's exact reply text and sender JID.

Related