Quick Start
Make sure you have completed the Installation guide. Desktop Homunculus and the official MODs should be installed and the app should be running.
Create Your First Persona
Learn what personas, MODs, and assets are in the Core Concepts page.
When you first launch Desktop Homunculus, no character appears on screen — you need to create a persona first.
- Click the Desktop Homunculus icon in the system tray (notification area)
- Select "Persona" to open the Persona Management dashboard
- Enter an ID (e.g.
elmer) and a Name, then click Create - Select a VRM model — the built-in
vrm:elmermodel is ready to use - Enable Auto-Spawn so the character appears automatically on future launches, then click Save
Your character should now appear on the desktop. It will idle, react when grabbed, and follow your cursor — powered by the built-in assets and the @hmcs/persona MOD.
Interact with Your Character
Drag and Move
Click and drag the character to reposition it anywhere on your desktop. While being dragged, the character switches to a "drag" state. Release to drop the character at the new position.
Character States
The character responds to different states, each with its own behavior:
| State | Trigger |
|---|---|
idle | Default state |
drag | Click and drag the character |
sitting | Drop the character on a window edge |
Right-Click Menu
Right-click the character to open the context menu overlay, which is built into the engine. From here you can access the per-character actions provided by installed MODs.
Settings
The settings panel is built into the engine. Open the system tray → "Settings" to show it; picking Settings again while the panel is open does nothing.
| Setting | Description |
|---|---|
| Frame Rate | The rendering frame rate (1–120 fps). Lower values reduce CPU/GPU usage. |
| Shadow Opacity | The transparency of the shadow panel overlay behind the character (0–100%). |
Changes are saved automatically and kept across restarts.
Persona Settings
Right-click the character and select "Persona" to open the per-persona settings panel. Here you can configure the character's identity (name, age, gender, personality) and appearance (bone scale adjustments).
To manage all your personas (create new ones, delete old ones), open the system tray → "Persona" to access the Persona Management dashboard.
Speech to Text
If you have the @hmcs/stt MOD installed, open the system tray → "Speech to Text" to access the STT control panel. Download a Whisper model, configure your preferred language, and use voice input with the AI Agent.
Exiting the App
- Find the Desktop Homunculus icon in the system tray (notification area)
- Click the tray icon to open the tray menu
- Select Exit
Exit is built into the tray menu and is always available, even when no MODs are installed. On Windows, the app is hidden from the taskbar and Alt+Tab, so use the tray to quit.
Explore Official MODs
Desktop Homunculus ships with a set of official MODs under the @hmcs scope:
| MOD | Description |
|---|---|
@hmcs/persona | Persona management UI and default behavior service — configure identity, personality, and appearance |
Additional MODs
You can extend Desktop Homunculus with optional MODs. Install any of them at any time using the CLI:
| MOD | Description |
|---|---|
@hmcs/voicevox | Text-to-speech integration using the VoiceVox engine |
@hmcs/stt | Speech-to-text with Whisper-based voice recognition (details) |
For AI-powered interaction, install OpenClaw externally and set up the @hmcs/openclaw-plugin bridge. See AI Integration for details.
The @hmcs/voicevox MOD requires the VoiceVox engine to be installed and running separately. Visit the VoiceVox website for installation instructions.
hmcs mod install @hmcs/voicevox @hmcs/stt
What's Next?
- MOD Development — Build your own MODs with the TypeScript SDK
- API Reference — Explore the full HTTP API documentation