Quart

Quart is an autonomous, context-aware AI chatbot for WhatsApp, built with Node.js, Baileys, and the Vercel AI SDK / OpenAI API.

Quart is designed to feel less like a command-driven bot and more like a real participant in the conversation. It can follow ongoing group chat context, understand quoted replies, react naturally, send GIFs, create polls, share locations, and keep a structured memory of conversations using SQLite.

---

Why Quart?

Most WhatsApp bots only respond when directly prompted.

Quart is different.

It is built to join conversations naturally, keep track of what is going on, and behave like a genuine group member rather than a rigid automation script. The goal is to make AI communication feel lightweight, useful, and surprisingly human.

---

Features

• Autonomous conversation awareness: can respond naturally when context suggests it is relevant.
• Talk to it: can respond with voice messages using GPT-TTS models.
• Quoted reply support: understands replied-to messages so context is not lost.
• Text formatting: can use text formatting in its messages
• GIF integration: searches and sends relevant GIFs using the Giphy API.
• Poll generation: creates interactive WhatsApp polls based on chat context or user requests.
• Location sharing: sends map pins and location data on demand.
• Emoji reactions: reacts to messages based on sentiment and context.
• SQLite memory: stores structured chat history locally with "better-sqlite3".
• Tool-aware prompt flow: maps tool calls and conversation state cleanly into the model context.
• Lean context handling: designed to stay efficient and cost-conscious.

---

Tech Stack

• Runtime: Node.js
• WhatsApp API: @whiskeysockets/baileys
• AI / LLM Framework: Vercel AI SDK / OpenAI API
• Database: better-sqlite3
• GIF Provider: Giphy API

---

Quick Start

Prerequisites

• Node.js v22.12.0 or higher
• A WhatsApp account
• An OpenAI API key
• A GIPHY API key

Running with Docker (Recommended)

Run the following command to instantly spin up Quart in a container:

docker run \
  -e OPENAI_API_KEY="your-openai-key" \
  -e GIPHY_API_KEY="your-giphy-key" \
  -v data:/app/data/ \
  cubrift/quart

Then follow the terminal instructions to scan the generated WhatsApp QR code. Authentication sessions and the chat history database will persist safely inside the data named volume.

Installation

Clone the repository:

gh repo clone cubrift/quart
cd quart

Install dependencies & setup environment:

npm install
npm run setup

Start Quart:

npm link
quart

For more commands, run:

quart -h

Then follow the terminal instructions to scan the generated WhatsApp QR code. Once authenticated, session credentials will be stored locally.

---

Contributing

Contributions of all sizes are welcome.

If you are interested in AI prompts, Node.js, WhatsApp automation, code quality, architecture, or documentation, Quart would be a great project to jump into.

Helpful contributions include:

• bug fixes
• refactors
• documentation improvements
• prompt engineering
• feature ideas
• tests
• issue triage
• performance improvements

Good First Contributions

A few especially useful places to help:

• improve or simplify the system prompt
• clean up message handling
• split large modules into smaller, clearer pieces
• improve SQLite schema design
• add better logging and error handling
• write setup docs or examples

Before Opening a Pull Request

Please try to:

• keep changes focused
• explain what the change does and why it helps
• include screenshots or examples where useful
• make sure the project still runs cleanly after your changes

If you find something confusing, open an issue. Clear bugs and unclear docs are both welcome contributions.

---

Roadmap

• WhatsApp conversation awareness
• Quoted reply context
• GIF support
• Poll generation
• Location sharing
• Local SQLite history
• Voice message support

Feel free to add to the roadmap!

---

Deployment

Quart is lightweight enough to run on a small VPS or other always-on Linux host such as Wispbyte. Using Docker is highly recommended for these setups.

A typical deployment flow looks like this:

1. Upload or clone the repository to your server
2. Configure the environment variables
3. Install dependencies
4. Run the bot with a process manager such as PM2

Example:

npm install -g pm2
pm2 start index.js --name quart-bot
pm2 save

Make sure your host keeps the process alive and has persistent storage available for session data and SQLite files.

---

Notes

Quart is actively evolving, so the codebase may change quickly as features are added and the architecture improves. If something looks rough, that is usually a sign that there is room for a good contribution.

---

Made with ❤ by David Skillman