🐣 Pet Runtime: Convert Codex-generated hatch-pet packages into runnable desktop pets with idle, movement, action switching, and interaction responses.
🖥️ Desktop Stage: A PySide6-powered runtime that connects bubbles, status, inventory, role management, and settings panels.
✨ AI Companion: Optionally connect OpenAI-compatible models so characters can chat, show bubbles, and provide contextual companionship.
English | 简体中文
Quick Start | View Preview | HatchPet Converter Guide | Runtime Architecture
Codex-generated Pets should not stay as asset packages
CodexPetLive is a Windows desktop runtime for Codex Pets. It can convert Codex-generated hatch-pet character packages into real desktop pets: they can idle on the desktop, move, switch actions, respond to interactions, and connect to bubbles, status, inventory, role management, settings panels, and optional LLM chat
You can think of Codex as a character incubator and CodexPetLive as the desktop stage. Codex creates the character; CodexPetLive lets that character walk out of a folder and become a companion, an interactive object, and an extensible desktop role
The project is built on top of the CodexPetLive / PySide6 desktop pet framework. It is suitable for showcasing AI-generated characters, building desktop companion apps, validating character assets, developing desktop pet interactions, or extending a simple Pet package into a complete desktop experience
If you like this desktop pet program, please click the ⭐ Star button in the upper-right corner. It means a lot to us
Because there is still a desktop runtime gap between “generating a character” and “actually having a character”
Codex Pet can hatch a character, but an asset package does not move by itself, handle clicks or dragging, show bubbles, maintain status, manage inventory, expose settings, or chat. CodexPetLive fills this last mile: it brings AI-generated Pets from folders, preview images, and asset sheets onto the real desktop
It is more like a stage than another asset repository. Characters can be switched, interacted with, and extended; developers can also use the same PySide6 desktop pet framework to connect Codex Pets to a richer desktop experience
If Codex lets a character be born, CodexPetLive lets that character start working beside you
The pet can stay near the bottom of the desktop and work together with the settings panel, role manager, LLM bubbles, and chat interface. The screenshots below show the current desktop runtime and control-panel experience
| LLM Provider And Bubbles | Chat Panel |
|---|---|
 |
 |
| Configure an OpenAI-compatible provider, endpoint URL, model name, API Key, and environment-variable fallback | The role chat interface supports contextual messages, role prompt entry, chat history saving, and AI-content notices |
| Bubble Behavior | Role Manager |
 |
 |
| Tune bubble mode, active chat, cooldown time, pat-triggered bubble probability, and status-triggered bubble probability | Add, switch, and launch different roles. Role assets can be extended through the resource directory or import flow |
| Basic Settings |
|---|
 |
| Adjust pet size, default pet, interface language, theme color, and access update, issue, and developer-documentation entries |
If you only want to run the desktop pet first, download the Windows package, unzip it, and double-click CodexPetLive.exe. The pet will appear on your desktop. You can switch roles, adjust size, change bubble behavior, configure LLM services, or use it as a daily desktop companion app from the settings panel
If you want to try Codex Pets, first download a pet package you like from Codex Pets. A standard hatch-pet package usually contains pet.json and spritesheet.webp; they describe pet metadata and the animation spritesheet
After getting a pet package, use the CodexPetLive conversion tool to turn it into a desktop role module:
python tools\hatchpet_to_peakdesk.py convert `
--input C:\Path\To\codex-pet-package `
--out-dir res\role\YourPetName `
--role-name YourPetName `
--overwriteAfter conversion, restart CodexPetLive and select the new role in Role Manager. For the full conversion flow, spritesheet requirements, and action mapping, see HatchPet Converter Guide
The latest version is CodexPetLive v0.8.6, and the Windows package is CodexPetLive-v0.8.6-windows-x64.zip
Download the zip, unzip it, and double-click CodexPetLive.exe. v0.8.5 is a historical version published before the rename, so the old package name and old exe name still appear in historical Release assets
Maintainers who need to build the Windows zip package can refer to the Windows Release Checklist
Use Python 3.12 by default. If PySide6 / Qt DLL compatibility is unstable on your machine, Python 3.9 can still be used for source verification. The project now keeps only one requirements.txt, serving both source runtime and Windows release builds:
apscheduler
pynput
PyInstaller>=6.19,<7.0
PySide6>=6.10,<6.12
PySide6-Fluent-Widgets>=1.10,<2.0
tendo
Pillow>=11.0,<13.0Install and run with conda:
conda create --name CodexPetLive_pyside python=3.12 -y
conda activate CodexPetLive_pyside
python -m pip install -r requirements.txt
python -m CodexPetLiveIf you already have a compatible Python 3.12 installation, you can also use a virtual environment:
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python -m CodexPetLivePillow>=11.0,<13.0 means Pillow 11.x or 12.x. It is not pinned to a single exact version; pip will choose a compatible version in that range
CodexPetLive can be understood in three layers: the outer layer is the transparent Qt window and control panels visible to users; the middle layer is runtime features such as actions, notifications, inventory, tasks, and LLM; the inner layer is role assets, configuration files, and local runtime data
A desktop pet can be understood as a “state machine on a transparent window”: users see a character moving, jumping, and interacting on the desktop, while the program is continuously processing states, events, timers, and resource configuration. In engineering terms, it is roughly desktop pet = Qt window + animation frames + behavior state machine + user data + event responses
| Category | Module | Description |
|---|---|---|
| Startup And Lifecycle | CodexPetLive/__main__.py | Creates QApplication, loads pet, notification, accessory, system panel, and dashboard objects, and wires them through Qt Signals |
| Startup And Lifecycle | Single-instance control | Uses tendo.singleton.SingleInstance() to prevent duplicate launches; a later process exits silently if an instance already exists |
| Startup And Lifecycle | Multi-screen and midnight timer | Reads screen list at startup, prefers the primary screen, and sets cross-day timers for daily state or event refreshes |
| Desktop Pet Runtime | CodexPetLive/CodexPetLive.py | Main pet window and runtime coordinator, responsible for character display, action switching, state changes, mouse interaction, and signal dispatch |
| Desktop Pet Runtime | Animation action system | Role actions are configured through act_conf.json and pet_conf.json; PNG frame sequences provide the actual visual output |
| Desktop Pet Runtime | Interaction behavior | Supports common desktop pet behavior such as clicking, dragging, following, falling, patting, and focus actions |
| Role And Asset System | res/role | Main role directory. Each role usually contains pet_conf.json, act_conf.json, action/*.png, info, and related assets |
| Role And Asset System | res/pet | Legacy mini-pet structure, kept for compatibility and reflecting the project's evolution from pet assets to role modules |
| Role And Asset System | CodexPetLive/conf.py | Reads role, action, item, and save configuration; this is the core domain-configuration layer |
| Notifications And Bubbles | CodexPetLive/Notification.py | Manages pop-up notifications, bubbles, and log forwarding |
| Notifications And Bubbles | CodexPetLive/bubbleManager.py | Manages dialogue bubbles triggered by events such as hunger, favorability, clicks, and focus |
| Notifications And Bubbles | LLM bubble integration | The bubble system can request short text from an LLM for specific events and display it back as a pet bubble |
| Accessories And Sub-pets | CodexPetLive/Accessory.py | Manages accessory, drop, sub-pet, mouse-decoration, and related window objects |
| Accessories And Sub-pets | Sub-pet following | Sub-pets can follow the main pet, stop following, be recycled, or appear independently as an extension of “main role + attached objects” |
| Dashboard | CodexPetLive/Dashboard/DashboardUI.py | Provides tabs for status, inventory, shop, daily tasks, and animation management |
| Dashboard | Status And Buff | The status page displays HP, FV, coins, Buffs, and related pet values; inventory items can affect these states |
| Dashboard | Inventory And Shop | The inventory manages items; the shop handles buying and selling. Signals keep coins and item counts synchronized |
| Dashboard | Tasks And Focus | The task page includes Pomodoro, focus time, progress tasks, and daily tasks, and can grant coin rewards |
| System Settings Panel | CodexPetLive/SpriteSettings/SpriteControlPanel.py | Main system settings window, including settings, chat, LLM provider, saves, roles, item MODs, and mini-pet tabs |
| System Settings Panel | CharCardUI.py | Handles role import, switching, and card display |
| System Settings Panel | ItemCardUI.py | Handles item MOD management |
| System Settings Panel | GameSaveUI.py | Supports save, load, rollback, and deletion operations |
| LLM Features | CodexPetLive/llm_client.py | Includes OpenAI, DeepSeek, Ollama, and Custom OpenAI-compatible provider presets |
| LLM Features | LLMChatUI.py | Provides the pet chat interface and supports chat-history saving |
| LLM Features | Safety boundary | API Keys are read from environment variables first, and can also be saved to llm_secrets.json in the runtime data directory |
| Packaging And Tools | tools/ | Contains HatchPet conversion helpers for turning other pet assets into the CodexPetLive structure |
| Packaging And Tools | docs/ | Contains source architecture, dependency map, asset development, and release checklist documents |
For more detail on source structure and dependencies, read Source Architecture and Dependency Map
Project configuration falls into three broad groups: repository default resource configuration, local runtime configuration, and optional LLM service configuration
| Type | Location | Description |
|---|---|---|
| Default roles and assets | res/role, res/pet, res/icons |
Distributed with the project, including role actions, avatars, bubbles, icons, items, and default resources |
| Role action configuration | pet_conf.json, act_conf.json |
Describes role base attributes, action sets, frame refresh, movement, anchors, and trigger conditions |
| Runtime config | %APPDATA%\CodexPetLive on Windows |
Stores user settings and runtime data; can be overridden with CODEXPETLIVE_CONFIG_DIR |
| Runtime data | %APPDATA%\CodexPetLive\data |
Stores user data such as settings.json, pet_data.json, act_data.json, and task_data.json |
| LLM API Key | Environment variable CODEXPETLIVE_LLM_API_KEY or llm_secrets.json |
Environment variable takes priority; otherwise the local runtime secret file is read |
| LLM chat history | llm_chat_history.json |
Stored in the local runtime data directory and should not be posted to public repositories or issues |
If you want to develop new pet characters, actions, props, or mini-pets, read Asset Development and HatchPet Converter Guide first
If you want to modify the runtime, settings panel, notifications, inventory, LLM, or release flow, read Source Architecture, Dependency Map, and the Windows Release Checklist first
No. CodexPetLive is a PySide6 desktop GUI application. It shows desktop windows, system panels, and tray-related interactions after launch. It does not provide a localhost web page
The current requirements.txt has consolidated dependencies for both source runtime and Windows release builds, and constrains PySide6 to the 6.10 series. The release checklist also uses an isolated Python 3.12 virtual environment by default. Qt desktop apps are sensitive to Python, PySide6, and native DLL compatibility; if Python 3.12 hits QtCore or similar dynamic-library loading issues on a specific machine, Python 3.9 can still be used for source verification
It means Pillow 11.0.0 or later, but lower than 13.0. It is a version range, not an exact pin, and it does not require manually installing one fixed version. Pillow is mainly used for image reading, processing, and asset-related flows
The project uses tendo.singleton.SingleInstance() for single-instance protection. If a CodexPetLive process is already running, a later launch exits to avoid multiple desktop pets competing for the same configuration and resources
LLM is optional. When enabled, the pet sends user input, required chat context, role prompts, and event text to the LLM provider configured by the user. API Keys are read from environment variables first and can also be saved in the local runtime configuration directory. Chat history is stored in the local runtime data directory
Do not paste API Keys, chat history, provider responses, or unredacted local paths into public issues, logs, screenshots, or PRs
Project code follows the repository LICENSE. Default assets, sample assets, third-party role/item modules, external fonts/icons/audio, and user-imported assets may have independent licensing boundaries. Confirm the asset source and license terms before redistribution or derivative work
The public repository welcomes these types of contributions:
- Feedback on pet startup, resource loading, role import, inventory, notifications, or settings panels
- Additional roles, item MODs, mini-pets, document examples, or screenshot explanations
- Fixes for path compatibility, release package auditing, resource location, UI behavior, and smoke tests
- Discussion of LLM chat, role bubbles, context management, and local privacy boundaries
Before submitting code, keep each PR focused and solve one clear problem at a time. If API Keys, chat history, provider responses, local absolute paths, or other private information are involved, redact them first. Security or privacy issues should preferably be reported privately to maintainers
CodexPetLive is not a small program bound to one fixed character. It is a desktop pet foundation that can keep changing clothes, actions, props, and personality. Users can treat it as a desktop companion app, asset creators can use it as a character asset lab, and developers can use it as a starting point for interaction demos or lightweight desktop tools
- Based on ChaozhongLiu/DyberPet
- UI refactoring is based on Fluent-Widgets, with thanks to zhiyiYo
- Some demo assets come from daywa1kr
- Early animation module logic references yanji255
- Dragging and falling calculation logic references WolfChen1996