thunguo/miku-on-desktop — explained in plain English
Analysis updated 2026-05-18
Run an animated AI desktop pet that chats and reacts to what is on your screen.
Delegate coding tasks from the desktop pet to Claude Code or Codex.
Let the agent control your mouse and keyboard for automated actions.
Deploy the pet as a kiosk display on a Raspberry Pi with an attached screen.
| thunguo/miku-on-desktop | 920linjerry-stack/capital-studio | adya84/ha-world-cup-2026 | |
|---|---|---|---|
| Stars | 16 | 16 | 16 |
| Language | Python | Python | Python |
| Setup difficulty | moderate | easy | easy |
| Complexity | 4/5 | 3/5 | 2/5 |
| Audience | developer | researcher | general |
Figures from each repo's GitHub metadata at analysis time.
Requires Python 3.12+, the uv package manager, and at least one AI provider API key entered through the settings panel before it can chat.
Miku On Desktop is a Hatsune Miku themed desktop pet powered by an AI agent. It shows up as a transparent floating window sprite that sits on your desktop, can be dragged around, and wanders on its own. Behind that character sits an AI agent loop that can chat with you, look at your screenshots, control your mouse and keyboard, call MCP tools, and hand off tasks to external command line agents like Claude Code or Codex. It also keeps a long term memory system that carries across sessions. The project supports routing between multiple AI providers, including Anthropic, OpenAI, Gemini, and Qwen through an OpenAI compatible interface, scheduling requests across four capability tiers called mini, fast, medium, and heavy, with configurable fallback between providers. The pet itself is built with PySide6 as a borderless transparent floating window that supports dragging, wandering by itself, and switching between multiple character art sets, with chat bubbles that stream their output and can show yes or no confirmation prompts. Built in tools cover things like analyzing screenshots, operating the mouse and keyboard, expressing emotional reactions, and reading and writing memory. It can act as an MCP host, connecting to local or remote MCP servers, and it supports Skills, which are packages written as Markdown files with YAML frontmatter that can be hot reloaded. It can also spawn internal sub agents for its own tasks, or delegate work to external CLI agents like Claude Code and Codex through the Agent Client Protocol. Its long term memory is organized into four layers described as semantic, episodic, emotional, and raw session memory, managed through its own memory panel. It can optionally start conversations on its own based on what is on your screen, how long you have been idle, and configured quiet hours. Running it requires Python 3.12 or newer and the uv package manager, on macOS or Windows. After installing with uv and running the app, a tray icon and floating pet window appear, and provider API keys and other settings are entered through a settings panel in the tray menu rather than environment variables. The project also documents a separate setup for running as a kiosk display on a Raspberry Pi with an attached screen.
A Hatsune Miku desktop pet powered by an AI agent that can chat, see your screen, control your mouse and keyboard, and remember past sessions.
Mainly Python. The stack also includes Python, PySide6, uv.
The README does not state a license for this project.
Setup difficulty is rated moderate, with roughly 30min to a first successful run.
Mainly developer.
This repo across BitVibe Labs
double-check against the repo, no cap.