https://github.com/not-elm/desktop-homunculus
Desktop mascot built with bevy
https://github.com/not-elm/desktop-homunculus
bevy desktop-pet vrm vrma
Last synced: about 2 months ago
JSON representation
Desktop mascot built with bevy
- Host: GitHub
- URL: https://github.com/not-elm/desktop-homunculus
- Owner: not-elm
- License: apache-2.0
- Created: 2025-02-24T17:48:00.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-28T09:12:07.000Z (3 months ago)
- Last Synced: 2026-03-28T09:13:21.738Z (3 months ago)
- Topics: bevy, desktop-pet, vrm, vrma
- Language: Rust
- Homepage: https://not-elm.github.io/desktop-homunculus
- Size: 95.7 MB
- Stars: 69
- Watchers: 4
- Forks: 5
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# desktop-homunculus
> [!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.
## Documentation
[](https://not-elm.github.io/desktop-homunculus/)
| I want to... | Go here |
| --------------------------------------------- | -------------------------------------------------------------------------------- |
| Install and run quickly | [Getting Started](https://not-elm.github.io/desktop-homunculus/getting-started/) |
| Build MODs (SDK, WebView UI, assets) | [MOD Development](https://not-elm.github.io/desktop-homunculus/mod-development/) |
| Integrate AI agents (MCP, Claude Code, Codex) | [AI Integration](https://not-elm.github.io/desktop-homunculus/ai-integration/) |
| Look up CLI and MCP tools | [Reference](https://not-elm.github.io/desktop-homunculus/reference/) |
## Features
- **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
## Download
- [Github Releases](https://github.com/not-elm/desktop-homunculus/releases)
> [!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](https://not-elm.github.io/desktop-homunculus/getting-started/installation) for step-by-step instructions.
## Platform Support
| Platform | Status |
| -------- | --------------------------------------------- |
| macOS | Fully supported |
| Windows | Supported (NVIDIA GPU configuration required) |
| Linux | Planned |
## Contributing
See the [Contributing Guide](https://not-elm.github.io/desktop-homunculus/contributing) for guidelines.
## License
This project uses a three-lane licensing model:
- **Rust code** (engine, CLI): [MIT](./LICENSE-MIT) OR [Apache-2.0](./LICENSE-APACHE)
- **TypeScript code** (SDK, UI, MCP server, mods): [MIT](./LICENSE-MIT)
- **Creative assets & documentation**: [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/)
See each package's `package.json` or `Cargo.toml` for its specific license.