Chat Buddy

A Highly Personalized, Personality-Driven WhatsApp AI Assistant

Built with the OpenAI Agents SDK · Custom Tools · Per-User Memory · Guardrails

Installation · Quick Start · Commands · Architecture · Chat Commands · Docker · Testing · Troubleshooting · FAQ · Security · Contributing

What is Chat Buddy?

Chat Buddy is an AI-powered WhatsApp assistant that runs entirely from your terminal. It acts as your personal proxy — answering messages, scheduling calendar events, and managing chats with a personality you define.

Features Overview

AI-powered WhatsApp assistant
Personalized conversational memory
Google Calendar scheduling support
WhatsApp QR authentication flow
Secure encrypted API key storage
Built-in guardrails and safety validation
Token optimization with message debouncing
Docker support for simplified deployment

Highlights

Feature	Description
Agentic Core	Powered by the OpenAI Agents SDK with dynamic tool-calling
Short-Term Memory	Per-user conversation context for natural, flowing replies
AES-256 Encryption	API keys encrypted locally — never stored in plain text
Guardrails	Output validation layer blocks unsafe or off-brand responses
Google Calendar	Schedule meetings & reminders directly from WhatsApp
Debounced Replies	Merges rapid user bursts into one AI call to reduce token usage
Zero Config Deploy	Install globally, run the wizard, scan QR — done

Prerequisites

Before installing Chat Buddy, make sure you have:

Node.js >= 18.0.0
npm installed
A WhatsApp account for QR linking
An OpenAI API key
(Optional) Google Cloud credentials for Calendar integration

You can verify your Node.js version with:

node -v

Installation

Terminal setup preview:

# Install globally
npm i -g chat-buddy

# Or run without global install
npx chat-buddy init

Use chat-buddy <command> after global install.

Use npx chat-buddy <command> only if not installed globally.

Requirements: Node.js ≥ 18.0.0

Quick Start

Follow these steps to launch Chat Buddy for the first time.

Step 1 — Initialize the setup wizard

chat-buddy init

This command configures your bot identity and API keys.

Step 2 — Start the bot

chat-buddy run

This launches the WhatsApp client and generates a QR code in your terminal.

Step 3 — Link WhatsApp

Open WhatsApp on your phone:

WhatsApp → Linked Devices → Link a Device

Scan the QR code displayed in the terminal.

Once connected, your AI assistant is ready to reply to messages on WhatsApp.

Setting Up Google Calendar API

To enable calendar features (scheduling meetings, reminders), you need to create Google OAuth 2.0 credentials.

Step 1: Create a Google Cloud Project

Go to Google Cloud Console
Click on the project dropdown (top-left) and select New Project
Name it (e.g., Chat Buddy or WhatsApp Bot)
Click Create and wait for the project to initialize

Step 2: Enable Google Calendar API

In the Cloud Console, go to APIs & Services → Library
Search for "Google Calendar API"
Click on it and select Enable
Wait for the API to be enabled (you'll see a blue "Manage" button)

Step 3: Create OAuth 2.0 Credentials

Go to APIs & Services → Credentials
Click Create Credentials (top button)
Select OAuth 2.0 Client IDs
For Application Type, choose Desktop application
Click Create
A dialog appears with your Client ID and Client Secret — copy these values

Step 4: Download Credentials (Optional)

In the Credentials page, find your newly created OAuth app
Click the download icon (⬇) to get credentials.json
This file is optional — Chat Buddy will prompt you for Client ID/Secret during setup

Step 5: Set Up Chat Buddy

When you run chat-buddy init, you'll be asked for a Google OAuth Client ID & Client Secret. You have two options:

Option	Process
Option A: Use OAuth (Recommended)	When prompted "Enable Google Calendar integration?", type `y`. Then provide your Client ID and Secret when prompted. Later, run `chat-buddy login` to generate an OAuth token.
Option B: Manual Setup	Set `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET` as environment variables instead of using the interactive setup.

Step 6: Generate OAuth Token

chat-buddy login

This opens your browser to Google's consent screen. Approve access and the token is saved to ~/.botwithaki/google/token.json automatically.

Verify Everything Works

Once set up, test with an in-chat command:

/schedule lunch meeting tomorrow at 2pm

If the calendar syncs successfully, your event appears in Google Calendar.

Commands

Chat Buddy provides a full CLI to manage your bot lifecycle:

`chat-buddy init`

chat-buddy init

Launches the interactive setup wizard. You'll be prompted to enter:

Prompt	Description
Username	Your name — the agent uses this to know who it represents
Agent Name	The bot's display name (e.g. "Luffy", "Jarvis")
OpenAI API Key	Your `sk-...` key that powers the AI agent
Google Calendar	Choose whether to enable calendar integration. If yes, provide your OAuth Client ID and Secret

All secrets are encrypted with AES-256-CBC and stored at ~/.botwithaki/config.json. They are never sent anywhere except to the respective API services.

Running init again will overwrite your existing configuration.

`chat-buddy run`

chat-buddy run

Starts the WhatsApp bot. This command:

Loads and decrypts your saved configuration
Falls back to .env file if no config is found
Validates that required API keys exist
Initializes the whatsapp-web.js client
Displays a QR code in the terminal for WhatsApp linking

First-time setup:

Scan QR to login:
┌──────────────────────────────────────────┐
│                                          │
│     █▀▀▀▀▀█  ▄ █ ▄ ▄  █▀▀▀▀▀█            │
│     █ ███ █ █  ▄ ▀█ █ █ ███ █            │
│     █ ▀▀▀ █ █ ▀▀██ ▄█ █ ▀▀▀ █            │
│     ▀▀▀▀▀▀▀ ▀▄▀▄▀ █ ▀ ▀▀▀▀▀▀▀            │
│     ██▀ ▄▄▀▀▀▄ ▄▄█▄ ▀█▀█  ▀▄▀            │
│     ▀ ▄▀ ▄▀▀▀▄█▄ █ ▄▀█  █▄▀██            │
│     █▀▀▀▀▀█  █▄▀▀███▄ ▀█ ▀█▀▄            │
│     █ ███ █ ▀█▄ █▄█ ▄  ▄▀█ ▄             │
│     █ ▀▀▀ █ ▀█▄▀▄▀▄▄████▀▀▄██            │
│     ▀▀▀▀▀▀▀ ▀▀  ▀▀▀ ▀▀  ▀  ▀▀            │
│                                          │
└──────────────────────────────────────────┘

Open WhatsApp → Settings → Linked Devices → Link a Device → Scan the code.

Subsequent runs: Your session is persisted automatically. No QR scan needed unless you run chat-buddy new --config to reset auth.

By default, user messages are debounced per user. If someone sends multiple quick messages, Chat Buddy waits briefly and replies once with a combined response.

`chat-buddy login` (alias: `chat-buddy log`)

chat-buddy login

Generates a Google Calendar OAuth token by opening the Google consent screen in your browser.

Detail	Value
Scope	`https://www.googleapis.com/auth/calendar`
Requires	OAuth credentials (auto-discovered or prompted)
Output	`~/.botwithaki/google/token.json`

This is required for the bot's calendar features (scheduling meetings, setting reminders).

Credentials note: You do not need to manually place credentials.json in your working directory anymore. chat-buddy login will auto-discover credentials from supported locations or prompt once for OAuth Client ID and Client Secret.

If you still prefer manual .env setup:

Go to Google Cloud Console

Create a project → Enable the Google Calendar API

Create OAuth 2.0 credentials (Desktop App type)

Export the Client ID and Client Secret into your .env file as GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET

`chat-buddy key`

chat-buddy key

Rotate your API keys without re-running the full setup wizard. Useful when:

Your OpenAI key has been compromised or expired
You want to switch to a different Google project
You're migrating to a new API key

How it works:

Loads your existing encrypted config
Prompts for new keys — leave blank to keep the current value
Re-encrypts and saves the updated config instantly

   API Key Rotation
  ─────────────────────────────────────────

  Leave a field blank to keep the current key.

   New OpenAI API key (sk-...): sk-proj-new-key-here
   Enable Google Calendar? (y/N/blank to keep current):
   New Google OAuth Client ID (leave blank to keep current):
   New Google OAuth Client Secret (leave blank to keep current):

   API keys updated securely!

`chat-buddy new --config`

chat-buddy new --config

The all-in-one reconfiguration command. Use this when you want to give your bot a fresh start:

Step	Action
Rename Agent	Change the bot's agent name (e.g. "Luffy" → "Jarvis")
Rotate Keys	Enter new OpenAI and/or Google OAuth Client ID & Client Secret
Reset WhatsApp	Deletes the saved WhatsApp session (`~/.botwithaki/.wwebjs_auth`)
Reset Google	Deletes the Google OAuth token (`~/.botwithaki/google/token.json`)

After running this, the next chat-buddy run will require a fresh QR scan and (optionally) re-running chat-buddy login for calendar access.

   Chat-Buddy — Full Reconfiguration
  ─────────────────────────────────────────

   New Agent Identity
     Current agent name: Luffy
   New agent name (leave blank to keep): Jarvis

   API Key Rotation
     Leave blank to keep the current key.
   New OpenAI API key (sk-...):
   Enable Google Calendar? (y/N/blank to keep current):
   New Google OAuth Client ID (leave blank to keep current):
   New Google OAuth Client Secret (leave blank to keep current):

  Clearing auth sessions...
     WhatsApp session cleared
     Google token removed

   Reconfiguration complete!

   Agent name: Jarvis
   API keys updated securely
   Auth sessions cleared — re-scan QR on next run

Message Debounce and Token Optimization

To reduce unnecessary token usage, Chat Buddy buffers rapid consecutive messages from the same user and sends one combined request to the agent.

How it works

User sends multiple quick messages.
Bot waits for a short pause window.
Messages are merged into one batched prompt.
Bot sends one AI reply instead of multiple separate replies.

Example:

Incoming: hey
Incoming: how are you
Outgoing: one combined reply after pause

Configure debounce delay

Set environment variable CHAT_BUDDY_RESPONSE_DEBOUNCE_MS.

Default: 2200
Minimum: 300
Maximum: 15000

Example:

CHAT_BUDDY_RESPONSE_DEBOUNCE_MS=1800 chat-buddy run

Note: command messages such as /time, /history, /reset, and /schedule are handled immediately and are not debounced.

Architecture

┌──────────────────────────────────────────────────┐
│                  WhatsApp Client                 │
│              (whatsapp-web.js + QR)              │
└───────────────────────┬──────────────────────────┘
                        │ incoming message
                        ▼
┌──────────────────────────────────────────────────┐
│              Message Handler Service             │
│       (routing, command parsing, flow ctrl)      │
└───────────────────────┬──────────────────────────┘
                        │
              ┌─────────┴─────────┐
              ▼                   ▼
┌──────────────────┐   ┌──────────────────────────┐
│  Memory Service  │   │   OpenAI Agent Runner    │
│ (per-user context│   │  (Agents SDK + tools)    │
│  last 15 msgs)   │   │                          │
└──────────────────┘   └────────────┬─────────────┘
                                    │
                        ┌───────────┴───────────┐
                        ▼                       ▼
              ┌──────────────────┐   ┌─────────────────┐
              │   Tool Layer     │   │  Guardrails     │
              │ • /time          │   │ • Output filter │
              │ • /schedule      │   │ • Safety check  │
              │ • /history       │   │ • Persona lock  │
              │ • Google Calendar│   │                 │
              └──────────────────┘   └─────────────────┘
                                              │
                                              ▼
                                    ┌─────────────────┐
                                    │  WhatsApp Reply │
                                    └─────────────────┘

In-Chat Commands

These commands can be sent directly in any WhatsApp chat to control the bot.

Command	Description	Example
`/history`	Display recent conversation context for debugging	`/history`
`/reset`	Clear the bot's short-term memory for your user	`/reset`
`/schedule`	Schedule a Google Calendar event using natural language	`/schedule lunch tomorrow at 2pm`
`/time`	Get the current time from the bot	`/time`

Project Structure

chat-buddy/
├── src/
│   ├── cli/                 # CLI commands
│   │   ├── index.ts         # Command registration (init, run, log, key, new)
│   │   ├── init.ts          # Interactive setup wizard
│   │   └── run.ts           # Bot startup logic
│   ├── config/              # Agent personality & protocol settings
│   ├── guardrails/          # Output validation & safety tripwires
│   ├── services/            # Message handling, memory, command parsing
│   ├── storage/             # Encrypted config & chat history stores
│   ├── tools/               # Agent-callable tools (time, calendar, etc.)
│   ├── utils/               # Google auth, banner, helpers
│   ├── bot.ts               # WhatsApp client configuration
│   └── index.ts             # Library exports for programmatic usage
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md

Security & Privacy

Layer	How it works
Encrypted Storage	API keys are encrypted with AES-256-CBC using a machine-derived key (hostname + username + salt). Config files are useless if copied to another machine.
Ephemeral Memory	Chat history lives only in RAM (last 15 messages per user). Cleared completely on restart. No remote databases.
Guardrails	A validation pipeline ensures the AI never exposes system config, generates offensive content, or responds to out-of-scope queries.
Restrictive Permissions	On Unix systems, config files are set to `600` (owner-only) and the storage directory to `700`.

Running with Docker

Chat Buddy includes a fully configured Docker setup. You can run the bot without installing Node.js or Chromium locally.

Ensure you have Docker and docker-compose installed.
Clone the repository and navigate into it.
Start the bot interactively:
```
docker-compose run --rm chat-buddy
```
If this is your first time, you can run the setup wizard inside Docker:
```
docker-compose run --rm chat-buddy npm run init
```
(Note: The QR code and prompts will appear directly in your terminal).

Your configuration, WhatsApp session, and Google tokens are automatically persisted in a Docker volume so you don't lose them when the container stops.

Development

# Clone the repo
git clone https://github.com/snackoverflowasad/chat-buddy.git
cd chat-buddy

# Install dependencies
npm install

# Build
npm run build

# Run in dev mode (build + start)
npm run dev

Testing Commands

A robust testing and quality assurance setup is configured using Vitest for unit testing, ESLint for linting, and Prettier for code formatting checks.

You can run the following commands during development:

# Run unit tests (one-time run)
npm test

# Run unit tests in watch mode
npm run test:watch

# Build the project (type check and compile)
npm run build

# Run ESLint to check for code style and quality issues
npm run lint

# Run Prettier to check if all files conform to the code formatting guidelines
npm run format:check

Test coverage

The tests/ directory contains a comprehensive unit test suite covering all core modules:

Test file	Module tested	What is covered
`banner.test.ts`	`utils/banner`	`center()` padding math, multi-line, edge cases
`configStore.test.ts`	`storage/configStore`	AES-256-CBC encrypt/decrypt, path helpers, `loadConfig` v2 decryption
`sessionMeetingStore.test.ts`	`storage/sessionMeetingStore`	In-memory store isolation, add/get/clear meeting state
`chatHistoryStore.test.ts`	`storage/chatHistoryStore`	Per-user append, history limits, clear, unknown user
`FileConversationStore.test.ts`	`storage/FileConversationStore`	TTL filtering, 20-message trim, missing file, clearSession
`agentProtocol.test.ts`	`config/agent.protocol`	Protocol shape, name, `allowGroupReplies`, description injection
`commandService.test.ts`	`services/command.service`	`/time` greeting windows, `/reset` by userId, `/history`
`messageHandlerService.test.ts`	`services/messageHandler.service`	Debounce clamp (min/max/NaN/decimal), env-var isolation
`memoryService.test.ts`	`services/memory.service`	`storeMessage`, `getHistory`, `clearHistory` delegation
`conversationService.test.ts`	`services/conversation.service`	File store constructor, session load/save
`createReminder.test.ts`	`tools/createReminder`	Zod input and output schema validation
`createMeeting.test.ts`	`tools/createMeeting`	Schema validation, `meetLink` URL check, tool execution
`googleAuth.test.ts`	`utils/googleAuth`	`resolveAuthContext` priority, `GoogleAuthError`, JSON shape
`agentGuardrails.test.ts`	`guardrails/agentGuardrails`	Fail-safe and fail-open paths, safety API unavailability
`runContext.test.ts`	`utils/runContext`	AsyncLocalStorage isolation, parallel independence

Testing setup contributed by @bhavyanjain3004. Extended test suite contributed by @Jay-Jay-Tee.

Installation Notes

During npm install, you may see some deprecation warnings.

These warnings originate from internal dependencies used by whatsapp-web.js and typically do not affect functionality.

If installation completes successfully, Chat Buddy should work normally.

Troubleshooting

Node.js version issues

If you encounter installation or runtime errors, verify your Node.js version:

node -v

Chat Buddy requires Node.js >= 18.0.0.

QR code not appearing

If the QR code does not display:

Restart the bot using chat-buddy run
Ensure your terminal supports UTF-8 rendering
Delete the existing WhatsApp auth session and retry

WhatsApp session disconnected

If WhatsApp disconnects unexpectedly:

chat-buddy new --config

Then relaunch the bot and scan the QR code again.

Google Calendar integration not working

Make sure:

Google Calendar API is enabled
OAuth credentials are correct
chat-buddy login completed successfully

Permission issues on Linux/macOS

If you encounter storage permission errors:

chmod -R 700 ~/.botwithaki

This resets secure directory permissions.

FAQ

Does Chat Buddy store my conversations?

No. Chat history is stored temporarily in memory and cleared when the bot restarts unless explicitly persisted by the user.

Do I need to scan the QR code every time?

No. WhatsApp sessions are persisted locally after the first successful login.

Can I use Chat Buddy without Google Calendar integration?

Yes. Google Calendar support is optional and only required for scheduling-related features.

Where are API keys stored?

API keys are encrypted locally using AES-256 encryption and stored securely on your machine.

Does Chat Buddy support Docker?

Yes. A Docker setup is included for easier deployment and environment isolation.

Contributing

We welcome contributions! Please see our Contributing Guidelines for more details on how to get started.

Please also adhere to our Code of Conduct when participating in this project.

License

This project is licensed under the MIT License.

Built with love by Asad Hussain

Name		Name	Last commit message	Last commit date
Latest commit History 207 Commits
.github		.github
docker		docker
docs		docs
public		public
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Chat Buddy

What is Chat Buddy?

Features Overview

Highlights

Prerequisites

Installation

Quick Start

Step 1 — Initialize the setup wizard

Step 2 — Start the bot

Step 3 — Link WhatsApp

Setting Up Google Calendar API

Step 1: Create a Google Cloud Project

Step 2: Enable Google Calendar API

Step 3: Create OAuth 2.0 Credentials

Step 4: Download Credentials (Optional)

Step 5: Set Up Chat Buddy

Step 6: Generate OAuth Token

Verify Everything Works

Commands

Available Commands

chat-buddy init

chat-buddy run

chat-buddy login (alias: chat-buddy log)

chat-buddy key

chat-buddy new --config

Message Debounce and Token Optimization

How it works

Configure debounce delay

Architecture

In-Chat Commands

Project Structure

Security & Privacy

Running with Docker

Development

Testing Commands

Test coverage

Installation Notes

Troubleshooting

Node.js version issues

QR code not appearing

WhatsApp session disconnected

Google Calendar integration not working

Permission issues on Linux/macOS

FAQ

Does Chat Buddy store my conversations?

Do I need to scan the QR code every time?

Can I use Chat Buddy without Google Calendar integration?

Where are API keys stored?

Does Chat Buddy support Docker?

Contributing

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 6

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`chat-buddy init`

`chat-buddy run`

`chat-buddy login` (alias: `chat-buddy log`)

`chat-buddy key`

`chat-buddy new --config`

Packages