An animated Codex desktop pet for Windows. CodexPet detects Codex activity, reflects its state in real time, and stays visible on the desktop without interrupting your work.
Important
The official mascots and visual assets included with this project belong to OpenAI/Codex and their respective owners. CodexPet claims no authorship or ownership over them. It is an independent, unofficial project that provides an alternative way to display them on Windows.
- Visual states tied to real Codex events: idle, working, attention required, task complete, blocked/error, and offline.
- Eight selectable pets: Codex, BSOD, Dewey, Fireball, Null Signal, Rocky, Seedy, and Stacky.
- A stable single window even when Codex creates temporary helper processes.
- Persistent position, size, language, and selected pet across sessions and updates.
- Per-user automatic startup with Windows.
- Manual update checks through GitHub Releases.
- English and Spanish interface, switchable from the context menu.
- Localized About dialog with the author and official mascot attribution.
- Per-user installation without administrator privileges.
- Windows 10 or Windows 11.
- Windows PowerShell 5.1 or PowerShell 7.
- A working Codex installation that runs
codex.exe. - Internet access only for checking or downloading updates.
- Open the latest release.
- Download
CodexPet-Setup.exe. - Run the installer and choose English or Spanish.
CodexPet is installed in %LOCALAPPDATA%\CodexPet. The Inno Setup installer creates Desktop and Start menu shortcuts, registers the watcher at Windows startup, and provides a native uninstaller.
- Drag the card with the left mouse button to move it.
- Resize it from the corners.
- Double-click it to open Windows Terminal with Codex.
- Right-click it to select a pet, change the language, manage Windows startup, check for updates, or close CodexPet.
| State | Color | Meaning |
|---|---|---|
| Idle | Purple | Codex is open and waiting for a request. |
| Working | Blue | A task is active. |
| Needs attention | Yellow | Codex is requesting approval or information. |
| Task complete | Green | The task completed successfully. |
| Blocked | Red | The task failed or was interrupted. |
| Offline | Gray | No active Codex process was detected. |
Open the context menu and select Check for updates. CodexPet only queries the latest public release of ezenwa/CodexPet through the GitHub API. If a newer version is available, it offers to open the official release page. It never downloads, installs, or runs an update automatically.
CodexPet locally processes structural event types from %USERPROFILE%\.codex\sessions to identify task state. It also reads local Codex SQLite telemetry to determine whether an approval is currently pending. It does not send prompts, responses, telemetry, or file contents anywhere. Update checks only send a standard HTTPS request to GitHub.
The pets distributed with CodexPet are official Codex visual assets. Their designs, names, and original files belong to OpenAI/Codex and their respective owners. This repository only presents them through an alternative desktop interface. CodexPet is not affiliated with, sponsored by, or officially endorsed by OpenAI.
The project is implemented with PowerShell and WPF and has no external runtime dependencies.
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\CodexPet.ps1To validate PowerShell syntax:
$tokens = $null
$errors = $null
[System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path '.\CodexPet.ps1'), [ref]$tokens, [ref]$errors) | Out-Null
$errorsGenerating dist\CodexPet-Setup.exe and dist\CodexPet-Setup.zip requires Inno Setup 6:
.\Build-Release.ps1 -Version 1.2.3CodexPet.ps1: WPF window, animations, languages, and update checks.CodexPet-State.ps1: incremental event reader and mapping of real Codex events to visual states.CodexPet-Watcher.ps1: detects the Codex process group and maintains one pet instance.installer/CodexPet.iss: native installation and uninstallation through Inno Setup.Stop-CodexPet.ps1: controlled shutdown before updating or uninstalling.assets/pets: pet animation frames.
- If the pet does not appear, confirm that
codex.exeis running. - If an update check fails, verify access to GitHub and try again from the context menu.
- The watcher log is stored at
%LOCALAPPDATA%\CodexPet\watcher.log. - To reinstall, run the latest installer. Your position, size, language, and selected pet are preserved.
See CHANGELOG.md for the release history in English or CHANGELOG.es.md for the Spanish version.