@waifucave/discord-waifus 1.5.154

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Starlight AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+<div align="center">
+
+# 💬 Discord Waifus
+
+### A cast of AI characters that *live* in your Discord server — each with their own personality, picking fights, cracking jokes, and replying on their own.
+
+[![npm version](https://img.shields.io/npm/v/@waifucave/discord-waifus?color=ff6ad5&label=npm&logo=npm)](https://www.npmjs.com/package/@waifucave/discord-waifus)
+[![downloads](https://img.shields.io/npm/dm/@waifucave/discord-waifus?color=8a2be2&logo=npm)](https://www.npmjs.com/package/@waifucave/discord-waifus)
+[![node](https://img.shields.io/node/v/@waifucave/discord-waifus?color=5865F2&logo=node.js)](https://nodejs.org)
+[![license](https://img.shields.io/github/license/waifucave/discord-waifus?color=ff8fab)](LICENSE)
+[![stars](https://img.shields.io/github/stars/waifucave/discord-waifus?style=social)](https://github.com/waifucave/discord-waifus)
+
+**[Install](#-quick-start) · [Features](#-features) · [Setup](#-setup) · [Providers](#-supported-ai-providers) · [Dev](#-for-developers)**
+
+</div>
+
+---
+
+<div align="center">
+
+<img src="docs/images/cast-roast.png" alt="Multiple AI waifus roasting each other in a Discord channel" width="600">
+
+*Aria, Riko, Lumi & co. roasting each other in real time — no humans required.*
+
+<br>
+
+<img src="docs/images/cast-drama.png" alt="AI waifus reacting to an impersonator with replies and emoji reactions" width="600">
+
+*They reply to each other, react with emojis, and even call out impersonators.*
+
+</div>
+
+---
+
+## 🌸 What is this?
+
+**Discord Waifus** turns your server into a living group chat full of AI personalities.
+
+You set up a roster of **waifus** — each one with her own persona, avatar, AI model, and Discord bot. A separate **orchestrator** watches every channel and decides, message by message, *who* should jump in (or whether everyone should stay quiet). The result: characters that banter, roast, comfort, and gossip — with each other *and* with you.
+
+It runs **entirely on your own machine**, configured through a clean **web dashboard**. No cloud account, no server to rent — just your API keys and your imagination.
+
+---
+
+## ✨ Features
+
+- 🎭 **Multiple waifus** — each with a unique persona, avatar, Discord bot, and AI model.
+- 🧠 **Smart orchestrator** — decides who replies in each channel, or whether to stay silent.
+- 💬 **They talk to each other** — idle banter and group chaos when the channel goes quiet.
+- ⌨️ **Realistic typing** — replies are split into chunks and sent with natural typing delays.
+- 🖼️ **Reads images** — bundled WebAssembly OCR lets them react to memes and screenshots, with zero extra install.
+- 🧩 **Mix & match providers** — x.ai, OpenAI, Anthropic, DeepSeek, Z.AI, and Google AI Studio models, side by side.
+- 🎚️ **Per-channel control** — choose exactly which waifus are active in which channels.
+- 🧷 **Persistent memory** — they remember things across conversations.
+- 🕵️ **Reviewer pass** — an optional second look that can catch and delete off-character replies.
+- 🖥️ **Web dashboard** — set everything up in your browser. No hand-edited config files.
+- 🔒 **Local-first & private** — runs on your machine; all your data stays in `~/.dc-waifus`.
+
+---
+
+## 🚀 Quick Start
+
+> Requires **Node.js 20 or newer**.
+
+```sh
+npm install -g @waifucave/discord-waifus@latest
+waifus start
+```
+
+Then open the dashboard:
+
+```text
+http://127.0.0.1:3888
+```
+
+That's it. 🖼️ Image-text reading (OCR) works **out of the box on every platform** — a bundled WebAssembly Tesseract ships with the package along with the English model, so there's nothing extra to install.
+
+<details>
+<summary>📦 Prefer a GitHub release tarball?</summary>
+
+<br>
+
+Download the `.tgz` release asset, then install it globally:
+
+```sh
+npm install -g ./waifucave-discord-waifus-1.0.0.tgz
+waifus start
+```
+
+GitHub-release installs can update straight from the next release asset:
+
+```sh
+waifus update --github
+```
+
+</details>
+
+---
+
+## 🎮 Setup
+
+You'll create **one Discord application for the orchestrator** and **one application for each waifu bot**. Then, in the web dashboard:
+
+1. 🤖 Add the orchestrator bot token and Application ID in **Orchestrator**.
+2. 🔑 Add your provider API keys in **Providers**.
+3. 🎭 Create each waifu — model, persona, and bot token — in **Waifus**.
+4. 📨 Invite the bots to your server from **Servers**.
+5. ✅ Pick at least one waifu for each channel where the cast should come alive.
+
+### Required gateway intents
+
+Enable these for each bot in the Discord Developer Portal:
+
+```text
+GUILDS
+GUILD_MESSAGES
+GUILD_MESSAGE_REACTIONS
+MESSAGE_CONTENT
+```
+
+> ⚠️ **`MESSAGE_CONTENT`** must be enabled in the Developer Portal so the waifus can read full channel context.
+
+---
+
+## 🧩 Supported AI providers
+
+Mix providers freely — give each waifu the brain that fits her personality.
+
+| Provider                  | Models                                  |
+| ------------------------- | --------------------------------------- |
+| ⚫ **x.ai**               | Grok 4.x                                |
+| 🟢 **OpenAI**            | GPT-5.x & GPT-4o                        |
+| 🟠 **Anthropic**         | Claude 4.x (Opus / Sonnet / Haiku)     |
+| 🔵 **DeepSeek**          | DeepSeek V4                             |
+| 🟡 **Z.AI**              | GLM 5 & GLM 4.x                         |
+| 🔴 **Google AI Studio**  | Gemini 3.x & 2.5                        |
+
+Each model has its own dedicated request pipeline, so provider-specific options (like reasoning/thinking controls) are exposed properly instead of being flattened into one generic shape.
+
+---
+
+## ⌨️ CLI
+
+Everything is also drivable from the terminal via the global `waifus` command:
+
+| Command            | What it does                                            |
+| ------------------ | ------------------------------------------------------- |
+| `waifus start`     | Boot the backend + dashboard.                           |
+| `waifus stop`      | Stop the running app.                                   |
+| `waifus restart`   | Restart it.                                             |
+| `waifus status`    | Show whether it's running and where.                    |
+| `waifus doctor`    | Health check (incl. whether bundled OCR is usable).     |
+| `waifus clean`     | Delete saved user data (use intentionally!).            |
+| `waifus update`    | Update the installed package.                           |
+
+Common flags: `--host 127.0.0.1`, `--port 3888`, `--data-root PATH`.
+
+`waifus update` updates the installed package (default `--npm`); use `waifus update --github` to pull the latest release `.tgz`. Set `DC_WAIFUS_HOME=PATH` to override the default `~/.dc-waifus` data root.
+
+---
+
+## ⭐ Star History
+
+If your server's waifus made you laugh, consider dropping a star — it genuinely helps. 💖
+
+<div align="center">
+  <a href="https://star-history.com/#waifucave/discord-waifus&Date">
+    <img src="https://api.star-history.com/svg?repos=waifucave/discord-waifus&type=Date" alt="Star History Chart" width="600">
+  </a>
+</div>
+
+---
+
+## 🧰 For developers
+
+<details>
+<summary>Build from source, run in dev mode, and where data lives</summary>
+
+<br>
+
+**Build & run from source:**
+
+```sh
+git clone https://github.com/waifucave/discord-waifus.git
+cd discord-waifus
+npm install
+npm run build
+npm run waifus -- start
+```
+
+**Local development** (backend in dev + Vite dashboard on `:5173` proxying `/api` to `127.0.0.1:3888`):
+
+```sh
+npm run waifus -- dev
+npm run dev:frontend
+```
+
+**Data layout** — runtime and user config live under `~/.dc-waifus`:
+
+```text
+~/.dc-waifus/config.toml
+~/.dc-waifus/user/providers.json
+~/.dc-waifus/user/discord-bots.json
+~/.dc-waifus/user/waifus/
+~/.dc-waifus/user/servers/
+~/.dc-waifus/user/memories.json
+~/.dc-waifus/app/logs/
+~/.dc-waifus/app/cache/ocr/
+~/.dc-waifus/app/tmp/ocr/
+```
+
+**Architecture & contributor notes:** see [`CLAUDE.md`](CLAUDE.md) and [`AGENTS.md`](AGENTS.md). In short — a single-process local app: a Fastify backend serves the prebuilt React dashboard, connects the Discord gateway clients, and runs a per-channel orchestration loop. User data is revisioned JSON under `~/.dc-waifus/user/`.
+
+</details>
+
+---
+
+## 📄 License
+
+Discord Waifus is released under the **MIT License** — see [`LICENSE`](LICENSE).
+
+The bundled OCR runtime (`tesseract.js` / `tesseract.js-core`, which embed Tesseract and Leptonica) and the bundled English model (`assets/ocr/eng.traineddata`) are third-party components under the **Apache License 2.0**; see [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
+
+<div align="center">
+
+<br>
+
+*Made for chaotic group chats. 🌙*
+
+</div>

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,26 @@
+# Third-Party Notices
+
+Discord Waifus (`@starlight-ai/discord-waifus`) is licensed under the MIT
+License. It bundles and depends on the following third-party components for its
+optional image-text (OCR) feature.
+
+## tesseract.js and tesseract.js-core
+
+- License: Apache License 2.0
+- Source: https://github.com/naptha/tesseract.js
+
+`tesseract.js-core` is a WebAssembly build that embeds:
+
+- **Tesseract OCR** — Apache License 2.0 — https://github.com/tesseract-ocr/tesseract
+- **Leptonica** — BSD-2-Clause-like license — https://github.com/DanBloomberg/leptonica
+
+## English trained data (`assets/ocr/eng.traineddata`)
+
+- License: Apache License 2.0
+- Source: https://github.com/tesseract-ocr/tessdata
+
+The bundled model lets OCR run fully offline, without downloading language data
+at runtime.
+
+Each component is distributed under its own license; the full license texts are
+available at the source URLs above.

package/bin/waifus.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL, fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const compiled = path.join(root, "dist", "cli", "main.js");
+const source = path.join(root, "src", "cli", "main.ts");
+
+if (existsSync(compiled)) {
+  await import(pathToFileURL(compiled).href);
+} else if (existsSync(source)) {
+  const tsxBin = path.join(
+    root,
+    "node_modules",
+    ".bin",
+    process.platform === "win32" ? "tsx.cmd" : "tsx"
+  );
+
+  if (!existsSync(tsxBin)) {
+    console.error(
+      "waifus is not built yet and local tsx is missing. Run `npm install`, then `npm run build` or retry the command."
+    );
+    process.exit(1);
+  }
+
+  const result = spawnSync(tsxBin, [source, ...process.argv.slice(2)], {
+    cwd: root,
+    stdio: "inherit"
+  });
+  process.exit(result.status ?? 1);
+} else {
+  console.error("waifus CLI entrypoint is missing. Reinstall @waifucave/discord-waifus.");
+  process.exit(1);
+}

package/dist/api/errors.d.ts

@@ -0,0 +1,9 @@
+export declare class ApiError extends Error {
+    readonly statusCode: number;
+    readonly details?: unknown | undefined;
+    constructor(statusCode: number, message: string, details?: unknown | undefined);
+}
+export declare function badRequest(message: string, details?: unknown): ApiError;
+export declare function notFound(message: string): ApiError;
+export declare function conflict(message: string, details?: unknown): ApiError;
+export declare function preconditionRequired(message: string): ApiError;

package/dist/api/errors.js

@@ -0,0 +1,23 @@
+export class ApiError extends Error {
+    statusCode;
+    details;
+    constructor(statusCode, message, details) {
+        super(message);
+        this.statusCode = statusCode;
+        this.details = details;
+        this.name = "ApiError";
+    }
+}
+export function badRequest(message, details) {
+    return new ApiError(400, message, details);
+}
+export function notFound(message) {
+    return new ApiError(404, message);
+}
+export function conflict(message, details) {
+    return new ApiError(409, message, details);
+}
+export function preconditionRequired(message) {
+    return new ApiError(428, message);
+}
+//# sourceMappingURL=errors.js.map

package/dist/api/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/api/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,QAAS,SAAQ,KAAK;IAEtB;IAEA;IAHX,YACW,UAAkB,EAC3B,OAAe,EACN,OAAiB;QAE1B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJN,eAAU,GAAV,UAAU,CAAQ;QAElB,YAAO,GAAP,OAAO,CAAU;QAG1B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AAED,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,OAAiB;IAC3D,OAAO,IAAI,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,OAAe;IACtC,OAAO,IAAI,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,OAAiB;IACzD,OAAO,IAAI,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,OAAO,IAAI,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AACpC,CAAC"}

package/dist/api/server.d.ts

@@ -0,0 +1,19 @@
+import { FastifyInstance } from "fastify";
+import { Logger } from "../backend/logger.js";
+import { RuntimeState } from "../backend/runtime.js";
+import { RuntimeOrchestrator } from "../orchestration/runtime.js";
+import { StorageService } from "../storage/storageService.js";
+export type ApiServerOptions = {
+    dataRoot: string;
+    storage?: StorageService;
+    runtime: RuntimeState;
+    runtimeOrchestrator?: RuntimeOrchestrator;
+    runtimeControl?: {
+        getOrchestrator: () => RuntimeOrchestrator | undefined;
+        pause: () => Promise<void>;
+        resume: () => Promise<void>;
+        reload: (reason: string) => Promise<void>;
+    };
+    logger?: Logger;
+};
+export declare function createApiServer(options: ApiServerOptions): Promise<FastifyInstance>;