PawPause

A pixel desktop companion that helps you pause, hydrate, and stay focused.

It is local-first: settings, stats, imported companions, and focus history stay on your machine.

Glossary / 术语表

English · 中文 · 日本語 · 한국어 · Français · Deutsch · Русский · العربية · Español

PawPause is a macOS and Windows desktop companion. It keeps a small pixel friend on your screen, nudges you to take breaks, reminds you to drink water, helps protect focus sessions, and supports PetDex-style companion imports.

Features

• Pixel companion: transparent, always-on-top, draggable desktop companion with animated states.
• Break intervention: optional screen-block break mode when a reminder is easy to ignore.
• Hydration reminders: water reminders with daily and historical stats.
• Focus mode: macOS active-window detection can trigger full-screen distraction nudges for blocked apps or keywords.
• Agent activity alerts: local Codex, Claude Code, OpenCode, and DeepSeek TUI events can trigger completion, failure, review-needed, and progress nudges.
• Pet imports: import pet.json + spritesheet.webp/png folders or zip packages in the app.
• PetDex compatibility: PawPause reads companions installed to ~/.codex/pets.
• Multilingual UI: English, Chinese, Japanese, Korean, French, German, Russian, Arabic, and Spanish.
• Dark mode: settings and companion UI adapt to system appearance.

Install

Download installers from Releases:

File	Platform
PawPause-x.x.x-mac-arm64.dmg	macOS Apple Silicon
PawPause-x.x.x-mac-x64.dmg	macOS Intel
PawPause-x.x.x-win-x64.exe	Windows 64-bit

On macOS, distraction detection and Agent window recognition require Accessibility permission.

OpenCode Agent Hook

PawPause can consume OpenCode lifecycle events through a small OpenCode plugin:

mkdir -p ~/.config/opencode/plugins
cp integrations/opencode/pawpause-agent-hook.js ~/.config/opencode/plugins/

The plugin writes JSONL events to ~/.local/share/pawpause/agent-events/opencode.jsonl. You can override that path with PAWPAUSE_AGENT_EVENTS.

DeepSeek TUI Activity

PawPause also watches local DeepSeek TUI activity without a plugin. It reads recent session updates from ~/.deepseek/sessions and approval events from ~/.deepseek/audit.log, so normal chats, tool use, completion, failures, and permission prompts can move the companion.

Import Companions

From PawPause

1. Open the PawPause settings window.
2. Go to the companion page.
3. Import a folder or zip containing pet.json and spritesheet.webp or spritesheet.png.

From PetDex

npx petdex install trump

PawPause scans ~/.codex/pets automatically, so installed companions usually appear without restarting.

Run From Source

git clone https://github.com/angziii/PawPause.git
cd PawPause
corepack enable
corepack pnpm install
corepack pnpm dev

Build

corepack pnpm typecheck
corepack pnpm build
corepack pnpm dist:mac
corepack pnpm dist:win

Project Structure

src/main/       Electron main process: windows, tray, timers, focus detection, imports
src/preload/    IPC bridge between Electron and React
src/renderer/   React UI for the companion and settings windows
src/shared/     Types, defaults, i18n, PetDex state mapping
landing/        PawPause landing page deployed to pawpause.vercel.app
docs/readme/    Localized README pages

Large companion asset packs are intentionally not committed to keep the repository small. Import or install companions locally instead.

Star History

License

Source code is released under the MIT License. Companion assets may have separate licensing; see ASSET_LICENSE.md.

Acknowledgements

PawPause is built with appreciation for:

• PawPal, the original Electron desktop companion foundation.
• PetDex, the inspiration for the pixel companion package format.