Starter X Chat bot powered by Grok and Grok Imagine.

Out of the box it is a Grok pass-through: encrypted DMs in, Grok out. /imagine generates (or edits) an image with Grok Imagine and sends it back as an encrypted Chat attachment.

The X Chat crypto, inbox, activity stream, and media path are already working. Put your product in xchat_bot/handler.py.

inbound ciphertext  → Chat XDK decrypt → handler.handle(Message) → Reply
Reply text/image    → Chat XDK encrypt → POST /2/chat/conversations/{id}/messages

Python 3.10+.

git clone git@github.com:xdevplatform/xchat-agent-skeleton.git
cd xchat-agent-skeleton
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env

Fill in .env:

Then:

python -m xchat_bot.main

Keep that process running. GET /2/chat/conversations only returns the primary inbox. DMs from people who don't follow the bot sit in Message requests. Set X_BEARER_TOKEN so the activity stream can discover those threads. Until then, put handles in CHAT_PEER_USER_IDS or ask people to follow the bot first.

python -m unittest discover -s tests

Anyone who DMs the bot gets a Grok reply, with per-user history.

Change the voice with GROK_SYSTEM_PROMPT in .env, or edit DEFAULT_SYSTEM_PROMPT in config.py.

handler.py is the product layer. The rest of the process (keys, decrypt, send, media) stays as-is.

from xchat_bot.handler import Message, Reply

class MyBot:
    def handle(self, message: Message) -> Reply:
        if message.text.lower().startswith("/imagine"):
            image = self.grok.imagine(message.text.split(" ", 1)[1])
            return Reply("Here you go.", image)
        answer = self.grok.chat([
            {"role": "system", "content": "You are a travel concierge."},
            {"role": "user", "content": message.text},
        ])
        return Reply(answer)

Wire it in main.py instead of GrokPassthrough. Reply.text is the DM body. Reply.image (optional bytes) is uploaded as encrypted Chat media.

Bots should use a Chat XDK key blob (CHAT_PRIVATE_KEYS_B64), not a Juicebox PIN. Never commit .env, never log plaintext or key material.