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

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

Commands

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.