codex-pet-in-linux 0.1.3

Unofficial floating Codex activity pet for Linux

Codex Pet in Linux

English | 한국어

An unofficial floating desktop pet that follows local Codex CLI and VS Code activity on Linux. It changes animation when Codex is running, needs input, finishes, or becomes blocked. Click it to return to the relevant terminal or VS Code conversation.

This package does not bundle a character or redistribute OpenAI pet artwork. It uses compatible pets already installed on your computer.

Install

1. Install system helpers

# Ubuntu / Debian
sudo apt install pipx wmctrl x11-utils

# Arch Linux
sudo pacman -S python-pipx wmctrl xorg-xprop

qdbus6 is optional and enables terminal-window focus on KDE Plasma.

2. Install with pipx

pipx install codex-pet-in-linux
codex-pet-in-linux --wake

The first launch creates the desktop menu entry automatically. pipx installs PyQt6 in an isolated environment and exposes the codex-pet-in-linux command.

If the command is not found, run pipx ensurepath, restart the terminal, and try again.

3. Provide a pet

The app discovers:

• compatible custom pets in ~/.codex/pets
• pets bundled with the installed Codex VS Code extension

If neither exists, the app shows an explanation instead of starting. See the official Codex Pets documentation for the custom-pet format and creation flow.

Update

pipx upgrade codex-pet-in-linux
codex-pet-in-linux --wake

To install the latest source checkout instead of the latest PyPI release:

git clone https://github.com/YeeDochi/Codex-pet-in-Linux.git
cd Codex-pet-in-Linux
./install.sh

Uninstall

Remove the desktop and autostart entries before removing the pipx package:

codex-pet-in-linux --remove-desktop
pipx uninstall codex-pet-in-linux

Custom pets in ~/.codex/pets and saved preferences are preserved. From a source checkout, ./uninstall.sh performs both steps.

What it shows

State	Meaning	Animation
Running	A local Codex chat is actively working	working
Needs input	Approval, an answer, or another decision is required	waiting
Ready	A chat completed and has unread activity	waving
Blocked	A chat failed or encountered a system error	failed

When several chats are active, the priority is needs input, blocked, ready, then running. Right-click the pet to open the activity list.

Commands

Command	What it does
codex-pet-in-linux --wake	Start the app or show the existing pet
codex-pet-in-linux --toggle	Show or hide the running pet
codex-pet-in-linux --quit	Stop the running pet
codex-pet-in-linux --check	Run the built-in self-check
codex-pet-in-linux --install-desktop	Create or refresh the desktop entry
codex-pet-in-linux --remove-desktop	Stop the pet and remove desktop integration

Left-click returns to Codex. Dragging moves the pet and saves its position. Right-click opens activities, pet selection, size, notifications, autostart, hide, and quit controls.

Compatibility

Hardware-tested on KDE Plasma 6 with Wayland/XWayland. The overlay, notifications, and taskbar behavior use Qt and standard X11 integration.

Exact CLI-window focus currently uses KWin and focuses the first supported Kitty, Konsole, Alacritty, WezTerm, or GNOME Terminal window. VS Code activation uses wmctrl. Other desktop environments may run the pet while providing less precise window focus.

Privacy

The app reads recent local metadata and status events from ~/.codex/sessions. It does not upload session data or call a network API.

Development

git clone https://github.com/YeeDochi/Codex-pet-in-Linux.git
cd Codex-pet-in-Linux
python -m venv .venv
. .venv/bin/activate
pip install -e .
QT_QPA_PLATFORM=offscreen python -m floating_codex_pet --check

Build validation:

pip install build twine
python -m build
twine check dist/*

Maintainer release

PyPI publishing uses GitHub Trusted Publishing for project codex-pet-in-linux, repository YeeDochi/Codex-pet-in-Linux, workflow publish.yml, and environment pypi. Publishing a GitHub release builds and uploads the matching version from floating_codex_pet/__init__.py.

License

Code: MIT. See LICENSE. No character artwork is included. This project is not affiliated with or endorsed by OpenAI.