Task Pet

A small Windows desktop pet that turns agent and automation activity into a visible status board. It uses an append-only JSONL event stream, keeps one row per stable session ID, and shows notifications only when a task changes state.

Download/watch the MP4 demo

Features

• Pixel-art desktop pet with two-frame state animations.
• Statuses: running, waiting, done, failed, and offline.
• Click the pet to open the Adventure Log.
• One row per session; progress updates replace the previous row state.
• Transition-aware notification queue avoids duplicate status alerts.
• Append-only events-<machine>.jsonl files for simple integrations.
• Claude Code hooks plus a generic CLI for other tools.
• No runtime Python packages beyond the Windows Python standard library and Tkinter.

Project structure

TaskPet/
├── task_pet.py                 # Application, event CLI, and self-test
├── start_task_pet.cmd          # Start the desktop UI
├── claude-hooks.example.json   # Claude Code hook configuration example
├── assets/                     # Pixel animation frames and bundled font
├── examples/
│   └── activity_progress.py    # Two-upload progress demo
├── demo/
│   ├── task-pet-demo.mp4       # Recorded demo
│   └── task-pet-demo.gif       # README preview
├── build/
│   └── TaskPetPortable.spec    # PyInstaller configuration
├── make_pixel_assets.py        # Regenerate images; requires Pillow
└── requirements-dev.txt        # Build/asset-generation dependencies

Install from source

Requirements:

• Windows 10 or 11
• Python 3.10+
• Tkinter (included in standard Windows Python installations)

Verify Python and Tkinter:

python --version
python -c "import tkinter; print('tkinter OK')"

Clone or download the repository, then start the UI:

.\start_task_pet.cmd

Equivalent command:

pythonw .\task_pet.py

Task Pet stores cursors and event files under %LOCALAPPDATA%\TaskPet. Set TASKPET_SYNC_DIR explicitly if you want another location or cross-device synchronization. Event titles can contain prompt text, so do not point this variable at shared storage unless that content is appropriate to share.

Run the progress demo

python .\examples\activity_progress.py

For a faster demo:

python .\examples\activity_progress.py --delay 0.25

The example keeps two stable activities visible:

• Demo package upload
• Source code upload

Each progresses through 0%, 25%, 50%, 75%, and 100%. At 50%, the demo package upload enters the orange waiting / INPUT state for approval, then resumes and completes.

Connect Claude Code

Copy the relevant entries from claude-hooks.example.json into ~/.claude/settings.json. Replace:

C:\path\to\TaskPet

with the absolute repository path. Restart Claude Code after changing hooks.

The example maps:

Claude Code event	Task Pet state
User submits a prompt	running
Permission/input notification	waiting
Tool use resumes after input	running
Turn stops with background or scheduled work	running
Turn stops without background work	done
Session ends	offline

Integrate another tool

Task Pet accepts JSON on stdin. Keep source and session_id stable to update one row.

'{"cwd":"C:\\src\\demo","session_id":"upload-42","prompt":"Upload | 50% | Uploading"}' |
  python .\task_pet.py --status "My Uploader" running

Finish it with the same session ID:

'{"cwd":"C:\\src\\demo","session_id":"upload-42","prompt":"Upload | 100% | Complete"}' |
  python .\task_pet.py --status "My Uploader" done

Available CLI operations:

--start SOURCE
--notify SOURCE
--status SOURCE running|waiting|done|failed|offline
--lifecycle SOURCE end|error
--message TEXT
--self-test

Test

python .\task_pet.py --self-test
python -m py_compile .\task_pet.py .\examples\activity_progress.py

Build the portable application

Install build-only dependencies:

python -m pip install -r .\requirements-dev.txt

Build:

python -m PyInstaller --noconfirm --clean `
  --distpath release `
  --workpath build\pyinstaller `
  build\TaskPetPortable.spec

Output:

release\TaskPetPortable\TaskPetPortable.exe

The full TaskPetPortable directory is the distributable application; it is not a single-file build.

Privacy

Task Pet makes no network requests. It records the source, machine name, project folder name, session ID, status, and up to 160 characters of prompt/title text in local JSONL files. Use TASKPET_SYNC_DIR only with storage whose audience is appropriate for that metadata.

Asset license

assets/ZhengGeDianHei-16.ttf is distributed under the SIL Open Font License. See assets/ZhengGeDianHei-16-OFL.txt.