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

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.

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

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.

Notes:

• When USE_MONGO=true, ensure MONGO_URI is reachable.
• If neither MySQL or 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

Katsumi/
├───src
│   ├───config
│   ├───core
│   ├───lib
│   │   ├───auth
│   │   ├───clonebot
│   │   ├───database
│   │   │   └───models
│   │   ├───schema
│   │   └───scraper
│   ├───plugins
│   └───utils
│       └───API
├─ ecosystem.config.cjs
├─ eslint.config.mjs
├─ .env.example
├─ package.json
└─ README.md

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`
		);
	},
};

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

• YouTube downloads fail with "Signature solving failed" or "Requested format is not available"
  This means yt-dlp cannot solve YouTube's JavaScript challenges. You must set up a JavaScript runtime and enable EJS components:

  • Install Deno (recommended):

    curl -fsSL https://deno.land/install.sh | sh

  • Ensure yt-dlp is updated (latest):

    yt-dlp --update-to nightly

    or

    python -m pip install -U --pre "yt-dlp[default]"

  The [default] extra installs yt-dlp-ejs (challenge solver scripts).

  • OR use remote EJS (if you can't install yt-dlp-ejs): Add to ~/.config/yt-dlp/config:

    --js-runtimes deno
    --remote-components ejs:npm

    Test with:

  yt-dlp --js-runtimes deno --remote-components ejs:npm -f "bestaudio" "https://youtu.be/mzB1VGEGcSU"

• 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.

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

MIT. See LICENSE.