PetRunner

Standalone macOS menu-bar and Windows tray renderer for Codex-compatible custom pets. It reads ${CODEX_HOME:-~/.codex}/pets without starting or connecting to Codex.

Start

PetRunner is independent from pet installers. Install pets with Petdex (or copy any compatible pet into the directory above), then run:

npx pet-runner start

On first use, the CLI checks the platform toolchain and builds PetRunner locally. Later runs open the installed build immediately. No repository clone or shell script is required.

Requirements:

• macOS 14 or later with Xcode Command Line Tools
• Windows 10/11 x64 with the .NET 10 SDK

Other commands:

npx pet-runner install
npx pet-runner update
npx pet-runner uninstall

To override the pet library:

npx pet-runner start --pets-dir /absolute/path/to/pets

See the complete setup guide for prerequisites, the manual source-build fallback, and troubleshooting.

Use the menu-bar or tray paw icon to choose or reload pets, change size, or quit. Drag the pet to move it, throw it toward a screen edge, hover or click it to jump, or drag its lower-right handle to resize. Idle uses the six standard frames at a calm, three-times-slower cadence, pausing for one second between each pass. Hover runs the three Codex jump cycles before returning to idle. V2 look-direction cells are reserved for a Computer Use cursor; this runner also uses recent physical pointer movement as a fallback, then resumes idle after the pointer settles.

Tests

macOS:

swift test
PETRUNNER_RUN_INSTALLED_PET_TESTS=1 swift test --filter InstalledPetsIntegrationTests

Windows:

dotnet run --project windows\PetRunner.Tests\PetRunner.Tests.csproj