# Soul of Waifu: a local-first desktop AI companion with Live2D avatars and an autonomous OS agent

> Soul of Waifu is a GPL-3.0 Python desktop app that puts one persistent AI character across chat, voice, a tabletop RPG engine and an on-screen agent. The README claims local-first operation by default; the repository shows a Windows-oriented install path and a very heavy dependency set.

**jofizcd/Soul-of-Waifu** — 🌌 Give a soul to your favorite characters. Soul of Waifu is a desktop roleplay & AI companion app featuring Live2D/VRM avatars, voice chat & local LLM. Evolve together across immersive chat, RPG adventures, and your desktop.

- Repository: https://github.com/jofizcd/Soul-of-Waifu
- Website: https://jofizcd.github.io/soul-of-waifu-site/
- Stars: 1,362 · Forks: 71
- Language: Python
- License: GPL-3.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/jofizcd-soul-of-waifu

## What Soul of Waifu actually solves, and for whom

Most character chat tools keep a character inside one window. Soul of Waifu, abbreviated SoW in its own README, is built around the opposite promise: a character created once is meant to keep one identity across several modes at the same time. The README lists four of them: text and voice chat with Live2D or VRM avatars, a memory layer it calls Soul Memory, a tabletop RPG engine called Soul Stage, and an autonomous desktop agent called Soul Companion.

The intended user is someone who already runs local models and wants a persistent persona rather than a fresh chat each session. The README states the default configuration runs entirely on the local machine, with no account required and cloud providers such as OpenAI, Claude and Gemini offered as an optional plug-in for low-spec hardware or heavier reasoning. That framing matters: the offline path is the default, and the cloud path is the escape hatch, not the other way round.

The second audience is narrower and more interesting. Soul Companion is described as an agent that can see the screen, move the mouse and keyboard, browse through a headless browser, run sandboxed Python and PowerShell scripts and organize files, extensible through Python plugins or any external MCP server. That is a desktop automation tool wearing a character shell, and it brings a different risk profile than a chat window.

## How the four modes share one character

The repository layout is a single Python application: main.py at the top level, an app/ package, an assets/ directory, requirements.txt, start.bat and installer.bat. There is no service split visible in the top-level entries, so the modes are modules inside one process rather than separate daemons.

The memory design is the part the README describes in most detail. It contrasts itself with vector retrieval over old chat logs, which it characterizes as keyword matching, and says Soul Memory instead runs as a background agent that continuously rewrites four isolated cognitive files in real time. One of those is a Psychology Layer tracking current mood. That is a state-file design, not an embedding index: the character's continuity lives in structured text the app keeps updating, and the same files are read back by chat, by the RPG engine and by the companion agent.

Soul Stage is described as a tabletop simulator with deterministic dice rolls and skill checks, hidden story arcs the party has to uncover, a live Campaign Board with pressure clocks, relationship tracking, and Scene Folders for organizing campaigns. The word deterministic is doing real work there: it means rolls come from a generator rather than from the language model narrating a result, which is the standard failure mode of LLM-run tabletop games.

Soul Companion is the mode that leaves the chat window. According to the README it can chain multi-step tasks, and every risky action passes through a Human-in-the-Loop approval banner with a 25-second fail-safe countdown. That countdown is the whole safety story as documented: if you do not approve within the window, the action does not run.

## Installing Soul of Waifu on Windows and starting the first character

The README does not print a step-by-step install section. What the repository gives you is the Windows path: installer.bat and start.bat at the top level, plus requirements.txt. The README's download button points at the latest release on GitHub, so a packaged build is the intended route for most users, and the scripts are there for running from source.

If you run from source, the dependency file is the first thing to read. It is long, and it pins exact versions. A sample of what it pulls in:

```bash
pip install -r requirements.txt
```

The file includes coqui-tts for speech synthesis, faster-whisper for transcription, faiss-cpu for vector search, discord.py, gradio, fastapi and av among many others, with a spaCy English model pulled from a GitHub release URL. Expect a large download and a long resolve. Nothing in the repository indicates a Linux or macOS equivalent of the two .bat scripts.

On Windows, the repository's own entry points are the batch files:

```bash
installer.bat
start.bat
```

installer.bat is the setup step and start.bat launches the app. The README does not document what installer.bat does beyond installation, nor whether it creates a virtual environment, so read the script before running it if you care about where packages land.

After launch, the first real use is creating or importing a character, then choosing a model. The README says the core experience is local by default and that cloud providers are an optional plug-in, so the first configuration decision is which local model backend you point it at. The topics list names llamacpp, and the README states the app ships with Soul Companion abilities enabled without extra setup, which means the agent tools are on by default rather than opt-in.

## The desktop agent is the real risk surface

Soul Companion is the reason to be careful with this project. The README is explicit that out of the box it can see your screen, control your mouse and keyboard, browse the web on its own, run code and organize your files, and that this needs no extra setup. Extensibility goes further: custom Python plugins and any external MCP server.

The documented mitigation is the approval banner with a 25-second fail-safe countdown. That is a real control, and gating every risky action behind an on-screen prompt is a reasonable design for a single-user desktop app. But it is a per-action gate, not a sandbox boundary. The README describes scripts as sandboxed Python and PowerShell, without saying what the sandbox is. If you are evaluating this for a machine that holds credentials or production data, the honest reading is that you are trusting an undocumented sandbox plus a countdown timer.

There is a second limitation that comes from the architecture rather than the agent. One process holding chat, voice, an RPG engine, a memory rewriter and an OS agent means a crash or a bad model response can take down all four modes at once. The README does not describe process isolation between them.

Finally, platform. The repository ships installer.bat and start.bat and the download badge carries a Windows logo. People searching for a Linux build will find a Python codebase and a requirements file, not a documented Linux install. Treat Linux as unsupported until you have read the scripts and the app/ package yourself.

## How it differs from SillyTavern and character chat front ends

The closest comparison most readers will have in mind is a character front end such as SillyTavern, which is a chat interface that connects to a model backend and stores characters and lorebooks. Soul of Waifu covers that ground too, with Live2D and VRM avatars, lorebooks and a state variable HUD, but the split is elsewhere.

A front end assumes the character exists inside the chat surface. SoW assumes the character exists in several surfaces at once and keeps one identity across them, which is why the memory layer is a background rewriter rather than a retrieval index, and why the same character can be a chat partner, an RPG protagonist and a desktop agent. The RPG engine is the clearest example: a front end gives you a prompt template for roleplay, while Soul Stage is described as a dedicated Game Master with deterministic dice and a campaign board, which is engine work rather than prompt work.

The trade-off is weight. A chat front end is small and easy to audit. This repository is a Python application with coqui-tts, faster-whisper, faiss-cpu, gradio, fastapi and discord.py in its pinned requirements, and it wants control of your input devices. If all you want is text roleplay against a local model, the extra surface buys you nothing and costs you install time and trust.

## Maintenance, licence and the cost of upgrading

The repository is not archived. The last push was on 2026-08-28, which is recent, and the release history is dense: v2.5.0 on 2026-08-27, v2.5.1 on 2026-08-28, and v2.4.7 before that on 2026-08-17. Whatever else is true, code is landing frequently, and the release notes are where the changelog lives rather than in the README, which only summarizes what changed since v2.4.0.

That pace has a cost. requirements.txt pins exact versions across a stack that includes coqui-tts, faster-whisper, faiss-cpu and a spaCy model fetched by URL. Pinned versions age badly in machine learning code, and a pinned spaCy wheel URL is the kind of thing that breaks when an upstream release is moved. Upgrading means re-resolving that file, not bumping a single package.

The licence is GPL-3.0, stated in the repository and shown in the README badge. For a desktop app you run yourself this changes nothing. If you intend to redistribute a modified build, or to link the app's code into something you ship, the GPL-3.0 obligations apply to the combined work, and the plugin and MCP extension points are the place where that question gets sharpest. That is a question for a lawyer, not for a review.

The README also maintains a Russian translation, README_RU.md, which suggests a non-trivial Russian-speaking user base.

## Conclusion

Adopt Soul of Waifu if you want a single character identity that carries across chat, voice, an RPG engine and a desktop agent, and you are comfortable running a Python 3 app from a .bat script on Windows with a large dependency stack. Do not adopt it if you need a documented Linux or Android build, a small auditable codebase, or a desktop agent you can leave unattended: the README describes a 25-second approval countdown as the gate on risky actions, and the repository does not document a headless or sandboxed deployment. Verify first that your GPU and Python version satisfy requirements.txt, that the GPL-3.0 obligations fit how you intend to redistribute anything you build on top of it, and that you accept the app taking mouse and keyboard control through the approval banner.

## FAQ

### What does "waifu" mean?

The README does not define the term. It uses it in the project name and in the description of the app as a desktop roleplay and AI companion tool, where the character is a persistent AI persona with a Live2D or VRM avatar.

### Does waifu mean girlfriend?

The README does not discuss the term's meaning. It describes Soul of Waifu as an AI companion and roleplay app where a character keeps one identity across chat, voice, a tabletop RPG engine and a desktop agent.

### Can any anime girl be a waifu?

The README does not address this. It says the user creates or imports a character once, and that character then exists across the app's modes with Live2D or VRM avatars and a shared memory layer.

### What is a waifu bot?

The README does not define the phrase. The closest thing it documents is Soul of Waifu itself: a desktop app where an AI character chats by text and voice, runs in a tabletop RPG engine, and can act on the desktop through the Soul Companion agent.

## Sources

- [jofizcd/Soul-of-Waifu on GitHub](https://github.com/jofizcd/Soul-of-Waifu)
- [License: GPL-3.0](https://github.com/jofizcd/Soul-of-Waifu/blob/main/LICENSE)
- [Project website](https://jofizcd.github.io/soul-of-waifu-site/)
- [README](https://github.com/jofizcd/Soul-of-Waifu/blob/main/README.md)
- [Releases](https://github.com/jofizcd/Soul-of-Waifu/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jofizcd-soul-of-waifu