Switch Codex pets and monitor usage limits from one lightweight Windows tray panel.
Local-first · Privacy-conscious · English, 简体中文, and 日本語
Download latest Windows installer · 简体中文 · Getting started
Codex Pet & Usage Companion is an independent, local-first Windows tray app for switching community Codex pets and viewing ChatGPT-backed usage limits from one compact panel.
This is an independent open-source project. It is not an official OpenAI product.
- Usage at a glance. See remaining Codex rate-limit windows, reset countdowns, read-only reset credits, low-usage alerts, and a private 24-hour or 7-day local trend. If a refresh fails, the last known reading remains visible and is clearly marked as stale.
- Community pet library. Discover Petdex pets from the app, then search, filter, inspect attribution, install, repair, uninstall, or switch pets. The library keeps separate All, Installed, and Favorites views, and can safely import compatible local ZIP or folder packages.
- Pet Workshop. Review every animation row and frame of an installed pet, surface transparent or edge-clipped frame warnings, edit creator and license metadata, and export a shareable package. Creator-friendly v1 and v2 templates make it practical to draw a custom pet in an art tool and bring it back into the library.
- Your data stays portable. Create a versioned settings backup with a restore preview; export local usage trends as CSV or JSON; and create a privacy-safe diagnostic report. These files remain local unless you choose to share them.
- Local, multilingual, and maintained. The interface supports English, 简体中文, and 日本語. Signed in-app updates show their release notes and require confirmation before installation; authentication and usage data stay within the official local Codex App Server flow.
Codex users often need two separate workflows: check subscription rate limits and open the official Pets settings to change a companion. This project brings those two tasks into one small tray panel while keeping authentication and usage data inside the official local Codex App Server flow.
The app launches codex app-server locally and communicates over its stable stdio transport. It does not scrape ChatGPT pages, read browser cookies, or upload usage data. Email addresses are masked in the UI, and raw protocol messages and access tokens are never logged.
The dashboard treats reset-credit information as strictly read-only. A missing App Server field remains unsupported/unknown and is never converted into a false zero. No redeem or account-changing action is exposed.
When local history is enabled, successful refreshes are sampled at most once every five minutes. Only the sample time, limit identifier, window duration, remaining percentage, and reset time are stored. History is capped, expires after seven days, never leaves the device, and can be disabled or cleared under Settings > Data & privacy.
The app includes an in-app client for the public Petdex manifest. It does not run a second floating mascot: it downloads the selected community package, validates its trusted asset URLs, metadata, size, image format, and v1/v2 sprite grid, then installs it under .codex/pets/<pet-id> for the official Codex app.
Install only adds the package without changing the active pet. Install and use refreshes the official Pets page, launches the desktop app when a trusted local executable is available, opens Settings > Pets through visible Windows UI Automation, invokes the visible Select button, and checks for the Selected state. If navigation or UI automation is unavailable, the package remains safely installed and the app asks the user to select it manually.
Pet assets remain owned by their Petdex submitters. The gallery links to each source page so users can review attribution and licensing before redistributing an asset.
Favorites are stored locally and give the library a quick shortlist without sending preference data to Petdex. The Pet Workshop works with installed or imported packages: inspect animation coverage frame by frame, review visual warnings, update metadata, export a safe ZIP, or generate an empty v1/v2 creator template for a new hand-drawn pet.
The Installed view can import either a ZIP or a folder containing pet.json and the referenced PNG/WebP spritesheet. Imports are limited by archive size, entry count, expanded size, path depth, metadata length, image format, and the Codex v1/v2 sprite grid. ZIP paths, symlinks, duplicate entries, unsafe source links, and ID conflicts are rejected before the existing package is changed.
Standard Codex fields are required: id, displayName, spritesheetPath, and optional spriteVersionNumber (1 or 2). Package creators may also declare description, author or submittedBy, license, sourceUrl (HTTPS), packageVersion, kind, and tags. These optional fields appear in the in-app details view and help users make informed attribution and redistribution decisions.
The app records a small sidecar only for packages it installs or imports. It contains the package origin, optional public attribution, source location, install time, and spritesheet checksum. It contains no account, authentication, or usage data. A repair is offered only while that recorded source remains available.
Download the latest Windows x64 installer from GitHub Releases.
The installer does not yet carry a commercial Windows Authenticode certificate, so Windows may display a warning on first install. In-app updates are separately signed and verified against the public key embedded in the app before installation.
- Windows 10 or Windows 11 (x64)
- Microsoft Edge WebView2 Runtime
- Codex CLI with
codex app-serversupport - A ChatGPT-backed Codex sign-in for subscription rate-limit information
- Internet access to
petdex.devandassets.petdex.devwhen browsing or installing community pets - No internet connection is required to browse, use, or re-import already available local packages
Check the CLI from PowerShell before launching the app:
codex --version
codex app-server --help- Download the latest
Codex Pet & Usage Companion_*_x64-setup.exeinstaller from the release page. - Run the installer for the current Windows user.
- Launch Codex Pet & Usage Companion from the Start menu or desktop shortcut.
- If Codex is not signed in, choose Reconnect and complete the official browser flow.
- Use the tray icon to show or hide the panel. Closing the panel hides it instead of exiting the app.
Starting with v0.8.1, the app checks GitHub Releases shortly after launch and every six hours. Use Settings > App updates or Check for updates in the tray menu for a manual check. The app shows release notes and asks for confirmation before downloading and installing a signature-verified update. Users on v0.8.0 or earlier need to install v0.8.1 manually once.
For Install and use, keep the official desktop app installed. The companion first tries standard Windows locations, then the optional path in Settings. You can still open Settings > Pets manually if the official UI does not expose the expected controls.
Development prerequisites:
- Node.js
20.19+,22.12+, or a newer supported release - Rust
1.96.0(selected automatically byrust-toolchain.toml) - Visual Studio 2022 Build Tools with the Desktop development with C++ workload and a Windows SDK
Install dependencies and run the checks:
npm install
npm run check
npm test
npm run buildStart the Tauri development app:
npm run tauri devBuild the Windows installer:
npm run tauri buildThe NSIS installer is written under src-tauri/target/release/bundle/nsis/.
Confirm that codex --version works in a new terminal, then restart the companion. Set CODEX_CLI_PATH to an explicit executable or command-shim path when the CLI is not on PATH.
Subscription rate-limit information requires a ChatGPT-backed Codex account. API-key-only and Bedrock authentication may not expose these usage windows. Use Reconnect and complete the official browser flow.
The in-panel warning works independently of Windows notification permission. The first system notification may require permission from Windows, and notification behavior is most complete after installing the bundled app rather than running an unpackaged development build.
Open Settings > Data & privacy to disable local history, switch between the 24-hour and 7-day chart, clear every saved sample, or turn reset-completion notifications off. Clearing history does not affect account usage or reset credits.
The close button hides the panel. Use the tray icon to show it again, or right-click the tray icon and choose Show panel.
The bridge uses only visible Windows UI Automation. Confirm the official desktop app is installed, optionally set its .exe path under Settings > Official desktop app, and retry Install and use. If navigation is unavailable after an official UI update, select the newly installed pet manually on Settings > Pets; the package remains safely installed.
Version 0.10.0 adds versioned settings backup and previewed restore, CSV/JSON usage-trend export, and privacy-safe diagnostics. It also adds Japanese language selection and end-to-end Japanese localization for the Petdex gallery and Pet Workshop. The release is published with a signed updater manifest and has passed native Windows export/restore verification. Pet packages are written only under .codex/pets; official client installation files are not modified.
- Add more interface languages and localized community documentation.
- Validate Windows 10/11 upgrade paths and pursue Authenticode signing for wider distribution.
- Evaluate additional usage windows and account actions only when the official Codex App Server exposes stable support.
See CHANGELOG.md for release history.
Codex Pet & Usage Companion is released under the MIT License.