potbot

A WhatsApp bot that keeps a shared-expense ledger from natural-language messages. It pairs to WhatsApp Web via neonize, runs a DSPy ReAct agent that calls tools (add_expense, remove_expense, list_expenses, show_balances) against a local SQLite database, transcribes voice notes via ElevenLabs, and serves a live Flask dashboard of the ledger.

Install

uv sync
cp .env.example .env   # then edit API keys + session name

Required env (see .env.example): POTBOT_LM, API_BASE, API_KEY, POTBOT_SESSION_NAME, POTBOT_LOG_PATH, ELEVEN_LABS_API_KEY, POTBOT_STT_MODEL. Optional: POTBOT_DB_PATH (default expenses.db), POTBOT_AGENT_MAX_ITERS (default 5).

Run

potbot               # local REPL — type messages, see dispatch output
potbot wa            # WhatsApp bot (scan QR code on first run)
potbot-dashboard     # Flask ledger dashboard (http://127.0.0.1:5005)

Equivalent: python -m potbot, python -m potbot wa, etc.

Slash commands (in-chat)

• /expenses [N] — list the last N active expenses (default 20).
• /balance — net per-member balance in this chat.
• /seed name1 name2 … — add synthetic participants under @local JIDs (test helper).

Notes

• The WhatsApp session file's name equals POTBOT_SESSION_NAME (default potbot-session). Do not commit it — it contains auth material.
• expenses.db is the source of truth for the ledger; conversation_log.jsonl is a full message audit. Keep both private.