waify

AI-powered daily message sender for WhatsApp, powered by OpenWA

Send a daily heartfelt message to someone you care about — automatically generated by AI, delivered via WhatsApp. Set it up once, and waify handles the rest.

Prerequisites

• Docker (for the WhatsApp API server)
• Node.js 22+
• A Google Gemini API key — get one free
• A WhatsApp account on your phone

Quick Start

npm install -g @deckasoft/waify
waify setup        # guided wizard: starts OpenWA, scans QR, configures everything
waify send         # send your first message

Commands

| Command | Description | | ---------------------------------- | ------------------------------------------------------------------------------------------------- | | waify setup | First-run wizard — starts Docker services, links WhatsApp, configures AI, recipient, and schedule | | waify send | Generate a message with Gemini and send it via WhatsApp | | waify preview | Preview generated messages without sending (-n 3 for multiple candidates) | | waify tui | Launch the interactive terminal UI (tabs: Home, History, Settings, Prompt, Schedule) | | waify history | View sent message log (--tail 20, --grep "pattern") | | waify config list | Show current configuration | | waify config get <key> | Get a single config value | | waify config set <key> <value> | Update a config value | | waify prompt show | Show the current AI system prompt and examples | | waify prompt edit | Open the prompt in $EDITOR | | waify prompt add-example <text> | Add a few-shot example to the prompt | | waify schedule list | List scheduled jobs | | waify schedule add <name> <cron> | Add a 6-field cron job (e.g. "0 0 9 * * *" — sec min hour dom month dow) | | waify schedule remove <name> | Remove a scheduled job |

Configuration

All config files live in ~/.config/waify/:

| File | Contents | | --------------------------- | ------------------------------------------------------------- | | config.json | OpenWA URL, session ID, recipient, message language, timezone | | prompt.json | AI system prompt + few-shot examples | | schedule.json | Scheduled send jobs (6-field cron) | | .env | API keys (Gemini, OpenWA) | | docker-compose.yml | Generated by waify setup | | Dockerfile / ofelia.ini | Generated by waify setup — sender image + scheduler config | | messages.log | Send history |

The OpenWA API key (OPENWA_API_KEY) is generated by the OpenWA server (random, per install) and auto-captured by waify setup from the container's /app/data/.api-key. There's no fixed default to set by hand — only the Gemini key is yours to supply.

Environment variable overrides:

| Variable | Default | Description | | ---------------- | ---------------------- | ------------------------- | | WAIFY_DATA_DIR | ~/.config/waify | Override config directory | | WAIFY_ENV_PATH | ~/.config/waify/.env | Override .env file path |

Scheduling

Scheduling runs on an Ofelia scheduler container that fires a transient sender container per job tick. waify setup generates the Dockerfile, builds the openwa-scripts-sender:latest image locally, and starts the scheduler — so scheduling works out of the box after setup.

In waify setup and the TUI you pick a time + frequency (Daily / Weekdays / Weekends / Custom days) and a timezone from a list — the cron is generated for you and evaluated in your local timezone. The CLI waify schedule add still takes a raw 6-field cron (sec min hour dom month dow) for power users. Changes restart the scheduler automatically; to restart manually:

waify schedule add morning "0 0 9 * * *"
docker compose -f ~/.config/waify/docker-compose.yml restart scheduler

You also choose the message language in setup and the TUI Settings tab; messages are generated in that language while reusing the example tone.

Powered by OpenWA

waify uses OpenWA as its WhatsApp API server. OpenWA runs locally in Docker and exposes a REST API that waify uses to send messages. All your WhatsApp data stays on your machine.

Roadmap

• [ ] Multi-recipient support (schema already supports arrays — currently capped at 1)
• [ ] Additional AI providers (OpenAI, Anthropic, Ollama) via the AIProvider interface
• [ ] Additional transport adapters (Telegram, SMS)
• [ ] NX monorepo with the deckasoft/openwa fork

Contributing

Contributions are welcome! See CONTRIBUTING.md for local setup, the branch/PR workflow, and our commit conventions — note that PR titles must be Conventional Commits, since they drive the automated release. Please also read our Code of Conduct. For security issues, see SECURITY.md — do not open a public issue.

License

MIT — see LICENSE