Quick Start · Download · Commands · Privacy · 한국어

Codex Pet Limit Rings for Windows draws translucent usage-limit rings around the Codex Desktop /pet avatar. It is a Windows companion implementation of petergpt/codex-pet-limit-rings using PowerShell, WPF, and Win32 window positioning.

Features

• Offers rings, dual bars, side gauges, corner frames, and reference-matched pixel-art potion orbs.
• Shows compact 5h and weekly remaining usage beside the pet in always mode, with detailed hover readouts still available.
• Keeps weekly usage in the weekly slot when an event removes the 5h limit, showing the unavailable 5h value as -.
• Adjusts position and spacing relative to the pet, including one-click centering.
• Scales potion orbs from 70-140% while preserving pet-relative spacing.
• Separates left 5h and right weekly hover readouts using Noto Sans KR.
• Selects Korean for South Korean public IPs and English elsewhere when language is set to Auto.
• Auto-detects and can start Codex Desktop.
• Requires a real, visible Codex Pet window instead of trusting persisted open state or stale bounds after reboot.
• Waits quietly until /pet is visible, then anchors both usage indicators to the pet's current live position.
• Uses a click-through WPF overlay, so it does not intercept mouse input.
• Installs a Windows Startup shortcut by default, so the helper waits quietly after login and shows the HUD as soon as /pet appears.
• Provides root .bat launchers for double-click install, settings, status, start, stop, and uninstall.
• Provides a cute cat-face icon in the Windows taskbar notification area; right-click it to open Settings, refresh usage, open logs, or quit.
• Keeps a click-through pet stand-in at the last verified position when Codex native voice temporarily hides /pet, then reconnects to the live pet automatically.
• Includes a three-step interactive feature tour in Settings, with usage, native-voice pet continuity, and customization focus states plus keyboard navigation.

Requirements

• Windows 10 or Windows 11.
• Codex Desktop installed and signed in.
• PowerShell 5.1 or newer.
• The Codex /pet overlay must be open for the usage HUD to appear.

Python is optional and only used for the local SQLite log fallback.

Download

For the easiest installation, open the latest GitHub release, download codex-pet-limit-rings-Win-0.1.26.zip, and extract the ZIP to a normal folder. Then double-click Install.bat or Manage.bat.

You can also download the repository source with GitHub's Code → Download ZIP button, extract it, and run the same installer. Developers can clone it instead:

git clone https://github.com/himomohi/Codexy-pet-usages-ring.git
cd Codexy-pet-usages-ring
.\Install.bat

Quick Start

Double-click Manage.bat for a single menu that installs, checks, configures, stops, or completely removes the companion.

• Install.bat installs, starts, and enables reboot-safe Windows auto-start.
• Install-AutoStart.bat provides the same persistent setup as an explicit compatibility entry point.
• Apply-Installed.bat applies later source edits to the trusted current install, preserves settings, and restarts it only when it was running.
• Uninstall.bat removes the running helper, shortcuts, and installed copy while keeping this source folder.

Open /pet in Codex Desktop after installation. The left/outer display is the 5-hour remaining allowance and the right/inner display is weekly remaining allowance. Hover a usage display for exact percentages, reset times, and a live countdown showing the remaining time. Pet continuity is enabled by default: if Codex native voice temporarily hides /pet, the helper keeps a non-interactive stand-in at the last verified pet position. This feature does not read text, use the microphone, or create a second voice.

The installer copies files to %LOCALAPPDATA%\CodexPetLimitRingsWin, starts the helper, and registers it at Windows login. The login task does not launch Codex Desktop; it waits quietly and displays the HUD when the Codex /pet overlay appears. Pass -NoStartup to the PowerShell installer to opt out.

PowerShell install:

powershell -ExecutionPolicy Bypass -File .\bin\powershell\Install.ps1

Direct PowerShell installs remain explicit: add -Startup for Windows auto-start, or use Install.bat for the recommended reboot-safe setup.

Commands

Double-click launchers:

Manage.bat
Install.bat
Install-AutoStart.bat
Apply-Installed.bat
Start.bat
Stop.bat
Status.bat
Settings.bat
Diagnose.bat
Uninstall.bat

When an install exists, these launchers automatically use the installed helper under %LOCALAPPDATA%\CodexPetLimitRingsWin.

The source and installed folders include reciprocal shortcuts (설치본 열기.lnk and 원본 프로젝트 열기.lnk) so either copy is easy to locate. Run Apply-Installed.bat after editing the source to update the installed copy without overwriting settings.json.

PowerShell:

.\bin\powershell\Start.ps1
.\bin\powershell\Stop.ps1
.\tools\Sync-Installed.ps1
.\bin\powershell\Status.ps1
.\bin\powershell\Settings.ps1
.\bin\powershell\Diagnose.ps1
.\bin\powershell\Uninstall.ps1

Useful install options:

.\bin\powershell\Install.ps1 -NoStartCodex
.\bin\powershell\Install.ps1 -Startup
.\bin\powershell\Install.ps1 -NoStartup -NoStartMenu -NoStart
.\bin\powershell\Install.ps1 -NoLiveUsage

Remove installed files too:

.\bin\powershell\Uninstall.ps1 -RemoveFiles

-RemoveFiles requires an install marker in the target directory to prevent accidental recursive deletion of the wrong folder.

Customize

Settings now opens the Pet Design Studio. Choose Quiet orbit, Potion float, Heartbeat, or Side by side; then tune each indicator's float, sway, or breathing motion, strength, duration, and pair timing. Save & apply updates the running overlay. Existing settings keep static motion until you choose a design.

The potion collection adds Celestial Orb, Rose Heart, Amber Star, Lunar Crescent, and Verdant Leaf to the six existing styles. Each card connects to the preview and Windows overlay. Changing the shape preserves colors and motion; recommended colors have a separate apply button.

Preview original idle and left/right running frames, pause or step through frames, test normal/low/weekly-only usage and light backgrounds, and export/import reusable JSON designs. Pet-frame playback is preview-only and sample usage never affects your account. When the selected pet cannot be identified, the studio labels its fallback to the most recent local custom pet.

Open Settings.bat or run:

.\bin\powershell\Settings.ps1

While the companion is running, left-click its potion icon in the Windows notification area to see 5-hour and weekly remaining usage, reset times, and freshness. The panel offers hide/show, refresh, settings, logs, and quit. Escape or an outside click closes it; the right-click menu remains available. Use Show hidden icons if the icon is folded away.

The image uses test values. The previous tray guide shows where the notification area is located.

The settings UI saves to:

%LOCALAPPDATA%\CodexPetLimitRingsWin\settings.json

You can change visualization style, colors, opacity, pet-relative placement and spacing, potion size, and hover readout colors and typography. The running helper automatically reloads settings file changes.

Privacy

The app reads these local Codex files:

• %USERPROFILE%\.codex\.codex-global-state.json
• %USERPROFILE%\.codex\auth.json
• %USERPROFILE%\.codex\logs_2.sqlite or logs_1.sqlite

It does not require an OpenAI API key and does not send pet images, screenshots, prompts, repository contents, or spritesheets anywhere.

When language is set to Auto (IP location), the app requests the caller's country code from https://api.country.is/. The service necessarily receives the public IP for the request, but the app stores only the returned two-letter country code in a local 24-hour cache. Select Korean or English explicitly to skip this lookup. If the lookup fails, the app falls back to the Windows UI language.

Live usage uses the local Codex access token only for:

https://chatgpt.com/backend-api/wham/usage

Disable live network usage with -NoLiveUsage.

The settings page runs a temporary 127.0.0.1 server with a random session token and writes only the local settings.json file.

Notes

• This is not an official OpenAI or Codex feature.
• The live usage endpoint is not a documented third-party API and may change.
• Rings appear only while /pet is open.

AI Install Handoff

Repository URL:

https://github.com/himomohi/Codexy-pet-usages-ring

Give an AI agent this repository URL and ask it to install the project on Windows:

Install Codex Pet Limit Rings for Windows from:
https://github.com/himomohi/Codexy-pet-usages-ring

If the repository is not local, clone it first. Then run Install.bat from the
repository root. After installation, run Status.ps1 and Diagnose.ps1 to verify
that the helper is installed, running, and waiting for or following /pet.

CLI equivalent:

powershell -ExecutionPolicy Bypass -File .\bin\powershell\Install.ps1
.\bin\powershell\Status.ps1
.\bin\powershell\Diagnose.ps1

More

• CHANGELOG.md
• SECURITY.md
• docs/troubleshooting.md
• docs/architecture.md
• NOTICE.md

Build a release zip:

.\tools\New-ReleaseZip.ps1

Feature and bug-fix releases should update VERSION, the README badge, and the top CHANGELOG.md section together.