Katsumi

Fast, modular WhatsApp bot built on Baileys. Plugin-system. Multi‑database.

---

Table of Contents

• Overview
• Why Katsumi?
• Feature Matrix
• Quick Start
• Configuration
• Project Structure
• Create a Plugin
• Scripts
• Troubleshooting
• Contributing
• License

Overview

Katsumi is a lean WhatsApp bot framework built on Baileys. Drop a plugin file in src/plugins/ and it becomes a command. Configure via .env, choose MySQL, MongoDB, or a JSON store, and deploy with PM2 or Docker.

Why Katsumi?

• Focused, minimal core
• Plugin‑first design
• MySQL / MongoDB / JSON storage
• Clean developer workflow (ESLint, Prettier, PM2)

Feature Matrix

Area	Capability	Status
Core	Baileys socket + message router	✅
Plugins	File‑based, auto‑loaded commands	✅
Storage	MySQL / MongoDB / JSON	✅
Config	Centralized .env	✅
DX	ESLint, Prettier, scripts	✅
Process Manager	PM2 ecosystem.config.cjs	✅
Docker	Example snippet (below)	▶️

Quick Start

git clone https://github.com/nat9h/Katsumi.git
cd Katsumi
npm install
cp .env.example .env

Edit .env, then run:

npm run dev   # development
npm start     # production
npm run pm2   # PM2 process

On first run, scan the QR code or Pairing code with WhatsApp.

Configuration

Variable	Description	Example / Default
MYSQL_HOST	MySQL host	localhost
MYSQL_PORT	MySQL port	3306
MYSQL_USER	MySQL user	root
MYSQL_PASSWORD	MySQL password	password
MYSQL_DATABASE	MySQL database name	baileys
USE_MONGO	Use MongoDB for storage (true/false)	false
MONGO_URI	MongoDB connection string	mongodb://localhost:27017/database
BOT_SESSION_NAME	Session storage identifier	session
BOT_PREFIXES	Comma‑separated command prefixes	!,.,?

Notes:

• When USE_MONGO=true, ensure MONGO_URI is reachable.
• If neither MySQL nor MongoDB is enabled, Katsumi falls back to a JSON store.

Docker (optional)

# Dockerfile (example)
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
CMD ["npm","start"]

# Build & run
docker build -t katsumi .
docker run --env-file .env --name katsumi --restart unless-stopped katsumi

Project Structure

Katsumi/
├─ src/
│  ├─ auth/
│  ├─ core/
│  ├─ database/
│  ├─ lib/
│  ├─ plugins/
│  ├─ plugins.js
│  └─ store.js
├─ ecosystem.config.cjs
├─ .env.example
├─ package.json
└─ README.md

Create a Plugin

Create src/plugins/ping.js:

import os from "os";
import { performance } from "perf_hooks";

export default {
  name: "ping",
  description: "Show latency and host info",
  command: ["ping", "p"],
  permissions: "all",      // all | admin | owner
  category: "info",
  cooldown: 0,
  async execute(m) {
    const t0 = performance.now();
    const total = (os.totalmem() / 1024 ** 3).toFixed(2);
    const free = (os.freemem() / 1024 ** 3).toFixed(2);
    await m.reply(
      `PONG
` +
      `Latency: ${(performance.now() - t0).toFixed(2)}ms
` +
      `CPU: ${os.cpus().length} cores
` +
      `RAM: ${free} / ${total} GB`
    );
  },
};

Plugin Options

Option	Description	Example
command	Triggers	["ping", "p"]
permissions	Access level	"all", "admin", "owner"
category	Help grouping	"info"
cooldown	Cooldown in seconds	0
group	Group chats only (optional)	true / false
private	Private chats only (optional)	true / false

Scripts

npm run dev       # watch mode
npm run lint      # eslint
npm run prettier  # format

Troubleshooting

• No QR: widen the terminal and check network; pairing code mode is supported.
• MySQL auth errors: verify host/user/password and database.
• Mongo errors: verify MONGO_URI and that USE_MONGO=true.
• Session issues: change BOT_SESSION_NAME and re‑login.

Contributing

Fork, create a feature branch, run lint, open a pull request with a clear description.

License

MIT. See LICENSE.