Metadata-Version: 2.4
Name: codex-pet-in-linux
Version: 0.1.4
Summary: Unofficial floating Codex activity pet for Linux
Author: YeeDochi
License-Expression: MIT
Project-URL: Homepage, https://github.com/YeeDochi/Codex-pet-in-Linux
Project-URL: Issues, https://github.com/YeeDochi/Codex-pet-in-Linux/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: X11 Applications :: Qt
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Desktop Environment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dbus-next<1,>=0.2.3
Requires-Dist: PyQt6<7,>=6.6
Dynamic: license-file

# Codex Pet in Linux

**English** | [한국어](README.ko.md)

[![PyPI](https://img.shields.io/pypi/v/codex-pet-in-linux)](https://pypi.org/project/codex-pet-in-linux/)
[![Check](https://github.com/YeeDochi/Codex-pet-in-Linux/actions/workflows/check.yml/badge.svg)](https://github.com/YeeDochi/Codex-pet-in-Linux/actions/workflows/check.yml)

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

```bash
# 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

```bash
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](https://developers.openai.com/codex/pets)
for the custom-pet format and creation flow.

## Update

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

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

```bash
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:

```bash
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

```bash
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:

```bash
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](LICENSE). No character artwork is included.
This project is not affiliated with or endorsed by OpenAI.
