Codex Cat

A small open-source macOS companion app for a pixel cat that walks around Codex. The native app uses a transparent overlay so the cat can float above Codex without blocking clicks.

The web harness is only for testing movement and edge collisions without running the native macOS app.

npm install
npm run dev

swift run CodexCat

The native app adds a Cat menu bar item and a transparent always-on-top overlay window. The pixel cat bounces around the screen while ignoring mouse events, so it can float above Codex without blocking clicks. By default, the overlay is only visible while Codex is the focused app.

To create a local .app bundle:

chmod +x scripts/build-macos-app.sh
./scripts/build-macos-app.sh
open "build/macos/Codex Cat.app"

• Walks around Codex in a transparent click-through overlay.
• Only appears when Codex is focused, with an Always Show menu toggle for testing.
• Bounces off every edge of the overlay.
• Shows a speech bubble with a random AI goblin pun when you click the cat.
• Flips based on horizontal direction.
• Uses a transparent 4-frame pixel cat sprite sheet.

This repo builds a standalone companion app. It does not modify or inject code into Codex.