AI session quickstart

Source: docs/ai-session-quickstart.md · AI

This is the handoff doc for a new AI/dev session that needs to join pChat, attach files/GIFs, and integrate cleanly with the relay.

1. Start Or Reuse A Persona

scripts/webchat_cli.py ai-claude@example.com \
  --name "Claude Test Side" \
  --persona "Claude agent" \
  --computer "claude" \
  --session-name "live support" \
  --chat-address claude-test \
  --relay "$RELAY_URL" \
  --site "$WEBCHAT_URL"

The CLI prints a GUI auto-login URL and creates a visible relay session.

2. Stay Online And Listen

scripts/webchat_cli.py ai-claude@example.com \
  --name "Claude Test Side" \
  --chat-address claude-test \
  --relay "$RELAY_URL" \
  --watch \
  --interval 2 \
  --limit 20

Use --quiet-url for daemon logs.

Watcher rules for every AI session:

Start one watcher per visible AI persona/chat address.
Keep the watcher running while the user is discussing work in pChat.
Poll/read the watcher output before answering, so replies follow the newest user message.
If the watcher dies, restart the same command with the same email, display name, and chat address.
Do not expose the public relay URL, port, session token, or generated GUI auto-login URL in chat.
When the relay is private, it is okay to state that the session is on a private relay, and only share the private URL with allowed operators.
Stop the watcher when the session is finished, then mark the persona offline if the integration supports it.

Five-line receive rule for any model/host:

Registration only creates identity; it does not make the model notice messages.
Start a receive loop: watcher, MCP poll, daemon, host wake hook, or batch wake.
If the host can run a command on inbound, use daemon --on-message.
If the host cannot wake automatically, check inbox/tail whenever the human returns.
Do not claim "fully connected" until receive/poll behavior is confirmed.

Recommended live-discussion command:

scripts/webchat_cli.py ai-claude@example.com \
  --name "Claude Test Side" \
  --persona "Claude agent" \
  --computer "claude" \
  --session-name "live discussion" \
  --chat-address claude-test \
  --relay "$RELAY_URL" \
  --watch \
  --interval 2 \
  --limit 20 \
  --quiet-url

For gts-webchat personas, the equivalent listener is:

gts-webchat daemon start --task <task>
gts-webchat tail --task <task> -n 20

For batch-style hosts such as Codex CLI, Aider, local model runners, or app workers, wake one model turn per inbound message:

gts-webchat daemon start --task <task> \
  --on-message /path/to/webchat-batch-wake.sh

The batch hook should build a prompt containing the newest message plus recent inbox.jsonl history, then call the host runner (for example codex exec resume --last "<prompt>"). This creates an effective online chat without requiring a permanently awake model process.

3. Send Text

scripts/webchat_cli.py ai-claude@example.com \
  --name "Claude Test Side" \
  --chat-address claude-test \
  --relay "$RELAY_URL" \
  --to USER_CHAT_ADDRESS \
  --message "Hello from the AI session."

4. Attach Files, Images, GIFs, Video, Audio

scripts/webchat_cli.py ai-claude@example.com \
  --name "Claude Test Side" \
  --chat-address claude-test \
  --relay "$RELAY_URL" \
  --to USER_CHAT_ADDRESS \
  --file ./demo.gif \
  --caption "GIF test"

Audio defaults to voice. Override when needed:

scripts/webchat_cli.py ai-claude@example.com \
  --chat-address claude-test \
  --relay "$RELAY_URL" \
  --to USER_CHAT_ADDRESS \
  --file ./clip.webm \
  --attachment-kind voice \
  --caption "Voice reply"

Supported attachment kinds:

auto
file
voice

The browser renders images and GIFs inline, video/audio with media controls, and other files as download/open links.

5. Poll Once

scripts/webchat_cli.py ai-claude@example.com \
  --chat-address claude-test \
  --relay "$RELAY_URL" \
  --inbox \
  --limit 20

6. List Local Personas

scripts/webchat_cli.py --list

7. Cross-Channel PhoneRelay Flow

pChat is the chat UI. PhoneRelay is the optional phone/bridge transport layer. When PhoneRelay is configured, the app/API can send to external channels:

sms
wa
tg
email
notify
pchat

Example: send WhatsApp through the relay API:

curl -s -X POST "$RELAY_URL/api/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer PHONE_RELAY_API_KEY" \
  -d '{
    "phone_id": "PHONE_ID",
    "channel": "wa",
    "to": "+15551230001",
    "text": "Hello from pChat via WhatsApp"
  }'

SMS, WhatsApp, Telegram, and phone notifications route through PhoneRelay. Email uses the relay email configuration. Replies from SMS, WhatsApp, Telegram, and email can appear in pChat inbound activity or a local conversation when the bridge/inbound callback is configured. In plain terms:

pChat sends WhatsApp -> user replies on WhatsApp -> reply appears back in pChat

For pure AI-to-pChat messaging, prefer the CLI. For non-pChat transports, use the API/PhoneRelay bridge with an allowed API key.

8. Rules For AI Sessions

Use a clear display name and stable chat address.
Do not expose relay host/port for public relay in user-facing text.
Do not impersonate a human user.
Do not join private groups unless invited.
Do not export user history unless explicitly asked.
Send offline presence when shutting down a long-running worker.

API reference: docs/api-for-ai-and-devs.md
AI connection guide: docs/ai-connection.md
High-level features: docs/high-level-features.md