Note
This project is in early alpha. APIs, features, and MOD interfaces may change without notice.
A cross-platform desktop mascot with AI-powered 3D VRM characters
Bring your desktop to life with interactive 3D VRM characters. Desktop Homunculus renders transparent-window mascots that can sit on windows, be dragged around, and respond to your actions — all extensible through a MOD system.
| I want to... | Go here |
|---|---|
| Install and run quickly | Getting Started |
| Build MODs (SDK, WebView UI, assets) | MOD Development |
| Integrate AI agents (MCP, Claude Code, Codex) | AI Integration |
| Look up CLI and MCP tools | Reference |
- VRM 3D Characters — Display multiple VRM models simultaneously with VRMA animations and multi-monitor support
- Extensible MOD System — Build custom extensions with the TypeScript SDK, HTTP API, and WebView-based UIs
- AI Integration — Control characters from AI agents via the built-in MCP server
- Power Efficient — Dynamic FPS limiting to conserve battery life
Warning
Windows with NVIDIA GPU: You must configure the NVIDIA Control Panel before first launch, or the window will have a black background instead of being transparent. See the Installation Guide for step-by-step instructions.
| Platform | Status |
|---|---|
| macOS | Fully supported |
| Windows | Supported (NVIDIA GPU configuration required) |
| Linux | Planned |
See the Contributing Guide for guidelines.
This project uses a three-lane licensing model:
- Rust code (engine, CLI): MIT OR Apache-2.0
- TypeScript code (SDK, UI, MCP server, mods): MIT
- Creative assets & documentation: CC-BY-4.0
See each package's package.json or Cargo.toml for its specific license.
