PawPause

What PawPause does

PawPause keeps a transparent, always-on-top, draggable pixel pet on screen. It offers break reminders with an optional screen-block mode, hydration reminders with daily and historical stats, custom daily reminders, and a macOS focus mode that detects the active window and can nudge when a blocked app or keyword appears. Pets can be imported as pet.json plus spritesheet folders or zip packages, and companions installed to ~/.codex/pets are read for PetDex compatibility.

For agents, PawPause can show completion, failure, review-needed and progress nudges. Hermes events arrive through a small plugin, pawpause-agent-hook, copied into ~/.hermes/plugins/ and enabled in ~/.hermes/config.yaml, which writes JSONL events to ~/.local/share/pawpause/agent-events/hermes.jsonl. Without the plugin, PawPause falls back to watching recent session files in ~/.hermes/sessions. Claude Code and DeepSeek TUI are detected from local session files with no plugin, OpenCode uses its own hook, and the README covers running Hermes in WSL with PawPause on Windows.

Key features

• Transparent, always-on-top pixel companion with animated states
• Break and hydration reminders, custom daily reminders and a macOS focus mode
• Hermes plugin that writes lifecycle events as JSONL, plus a ~/.hermes/sessions fallback
• Also reacts to Codex, Claude Code, OpenCode and DeepSeek TUI activity
• Pet imports and PetDex compatibility
• UI in nine languages with dark mode

When to use it

• Getting a nudge when a Hermes run finishes, fails or needs review
• Taking breaks and staying hydrated during long agent sessions
• Running Hermes in WSL while the pet runs on Windows

Who it is for: Developers who run Hermes Agent or other coding agents for long sessions and want desktop reminders and completion alerts.

How it fits with Hermes Agent

Supports Hermes Agent among other agents through an optional Hermes plugin and a session-file fallback; it is a general desktop companion, not Hermes-specific.

How to install PawPause

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

mkdir -p ~/.hermes/plugins
cp -R integrations/hermes/pawpause-agent-hook ~/.hermes/plugins/

Requirements: macOS (Apple Silicon or Intel) or Windows 64-bit; Accessibility permission on macOS for distraction detection and agent window recognition

Note: GitHub could not identify a license for this repository, so check the license terms before reuse.

FAQ