Codex Pet Patcher

Keep custom Codex CLI pet animations running for the entire task—even beyond the built-in three-minute limit—while still stopping correctly when work completes or is interrupted.

Codex Pet Patcher is a fail-closed Linux launcher for terminal pets such as Killua from Petdex. It builds against the exact installed Codex version, runs focused lifecycle tests, and uses the patched binary only after validation. Official Codex remains the automatic fallback.

Quick install

You need Codex CLI installed through npm on Linux. Then run:

curl -fsSL https://raw.githubusercontent.com/Soontosh/codex-pet-patcher/main/install.sh | bash

That command:

1. Checks Codex and build requirements.
2. Installs Rust automatically when needed.
3. Adds the guarded codex launcher to Bash.
4. Starts a background build for your exact Codex version.
5. Keeps using official Codex until every validation check passes.

The initial optimized build can take 15–30 minutes and use roughly 30 GiB of temporary disk space. Check it at any time:

codex-pet-patch status

What changes

Codex event	Pet behavior
Task starts	The custom running animation begins and loops without a timeout.
Task runs longer than three minutes	The animation continues.
Task completes	Codex replaces the running state with its ready/review state.
Task is interrupted	The running state is explicitly cleared and the pet returns to idle.
Codex needs input or fails	The appropriate waiting or failed state replaces running.
Codex updates	A new version-matched build starts; official Codex is used until it passes.

Safety model

The installer does not overwrite Codex inside node_modules.

A patched executable is activated only when all of these match:

• Installed Codex version
• SHA-256 of the official executable
• SHA-256 of the source patch
• Exact upstream source tag (rust-v<version>)

Every build must also pass:

• Running notifications remain active after a simulated year.
• Waiting, review, and failure notifications still expire normally.
• Clearing a notification returns the pet to idle.
• Interrupting a turn clears the running pet state.
• Patched and official --help output match.
• Patched and official feature lists match.

If the source changes, a test fails, or CLI behavior differs, the patch is rejected and official Codex runs instead.

Commands

codex-pet-patch status   # Current version and validation state
codex-pet-patch disable  # Always use official Codex
codex-pet-patch enable   # Re-enable guarded automatic patching
codex-pet-patch retry    # Retry a failed build on next launch

Logs live in ~/.local/share/codex-pet-patcher/logs/.

Requirements

• Linux x86-64
• Bash
• Codex CLI installed globally through npm
• About 30 GiB of free disk space during a new-version build
• A C compiler, make, and Perl (sudo apt install build-essential perl on Ubuntu/Debian)

The installer handles the Rust toolchain and rustfmt automatically.

Custom pet setup

This project controls Codex’s pet lifecycle; it does not redistribute character artwork. Install your pet separately and select it in ~/.codex/config.toml.

Example for Petdex:

npx petdex install killua

[tui]
pet = "custom:killua"

Your custom pet manifest must define a looping running animation. See the complete setup guide.

Updating and uninstalling

Update Codex normally. The launcher detects the new official checksum and automatically starts a separate validated build.

To remove the launcher while keeping cached binaries:

bash ~/.local/share/codex-pet-patcher/uninstall.sh

To remove everything:

bash ~/.local/share/codex-pet-patcher/uninstall.sh --purge

Compatibility

The source patch currently targets the pet lifecycle introduced in Codex CLI 0.144.1. Compatible future versions are patched automatically. If upstream changes prevent a clean patch, Codex Pet Patcher deliberately falls back to official Codex until this repository is updated.

Contributing

Bug reports and compatibility updates are welcome. Read CONTRIBUTING.md before submitting a pull request. Please report security issues through the process in SECURITY.md.

License and trademarks

Licensed under Apache-2.0. This is an independent community project and is not affiliated with or endorsed by OpenAI or Petdex. Character names and artwork belong to their respective owners; no pet artwork is included here.