XMPP Debugger — скилл

---
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.