# PawPal puts a transparent dog on top of your desktop to nag you about breaks

> PawPal is an Electron desktop pet for macOS and Windows whose transparent always-on-top dog reminds you to take breaks, drink water and stop scrolling social media. It is local-first, bilingual, and honest about the fact that its distraction detection currently works only on macOS.

**zebangeth/PawPal** — 一只住在你桌面上的小狗，提醒你休息、喝水、保持专注 | A little dog living on your desktop, reminding you to take breaks, stay hydrated, and keep focused.

- Repository: https://github.com/zebangeth/PawPal
- Stars: 588 · Forks: 85
- Language: TypeScript
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/zebangeth-pawpal

## A transparent always-on-top window that is only a pet

PawPal is a desktop pet app for macOS and Windows. A transparent, always-on-top dog lives on your screen and gently reminds you to take breaks, drink water, and stay focused. The project description captures the intent more plainly: a tiny desktop dog that helps you pause before you burn out.

The design constraint that shapes everything is transparency. The window has no background, sits above your other windows, and the pet is the only thing visible. That means the app is not a dashboard or a window in your taskbar, it is a small animated character that crosses the screen occasionally and otherwise gets out of the way.

The features are three reminders and some presentation. Break reminders are timed nudges to get up and move, and the dog runs across your screen to get your attention. Hydration reminders tell you to drink water. Focus mode detects what app you are using, and if you are on social media the dog nudges you back to work. There are multiple pet styles, currently a line-drawing dog and a golden retriever puppy, and the interface switches between Chinese and English.

The audience is a person who has decided that a nagging animal is more effective than a system notification, and who is willing to let a small Electron app observe which application has focus in order to notice social media use.

## Focus mode needs macOS accessibility permission, and does not exist on Windows

The two platform notes in the documentation are the most important operational facts about the app, and they are easy to miss if you only read the feature list.

On macOS, the first launch may prompt that the developer cannot be verified, and the instruction is to allow it in System Settings, Privacy and Security. The same note then says that the distraction detection in focus mode requires granting Accessibility permission. That is a significant ask, and it is not a small one: Accessibility permission on macOS is the permission class that lets an app observe what other applications are doing, which is exactly what focus mode needs and also exactly what a sceptic would want to know about.

On Windows, the documentation states the distraction detection feature is currently unavailable, since it is macOS only, while the other features work normally.

So the honest summary is that two of the three features, break reminders and hydration reminders, work on both platforms, and the one feature that reads your app usage works on macOS only. The topic list on the repository includes no platform-specific tags, so a user who assumes symmetry between macOS and Windows will find out at install time.

The development roadmap confirms the gap is known and planned. The unchecked items are more pet styles, sound effects, Windows distraction detection, and multi-display adaptation improvements.

## Local-first means the network is only touched for update checks

The data policy is the part of the design that deserves the most attention, because a screen-watching app has obvious reasons to phone home.

The documentation states that settings and statistics stay on your machine, and that PawPal only contacts GitHub Releases when you manually check for updates or opt in to launch-time checks. That is a real commitment in the structure of the app rather than a promise in a privacy policy, because the storage layer is electron-store, which is local persistence, and the only network call described is an update check against GitHub Releases.

The project structure shows where the pieces sit. The main process handles window management, the tray menu, timers, persistence, focus detection, and the update check. There is a preload directory that is the IPC bridge layer, a renderer directory with the React UI for the pet window and the settings window, a shared directory holding the shared types, default configuration, i18n and the pet appearance definitions, a tests directory for the pure logic tests, and a pet_assets directory for the pet animation assets, which are GIFs.

The split between main, preload, renderer and shared is the standard Electron security layout, with the preload script as the only bridge between the renderer and Node. The fact that focus detection lives in the main process rather than the renderer is consistent with that, since detecting the focused application is a main process job.

The updater design is worth noting for a small utility. The opt-in launch-time check means the default behaviour is to contact nothing, and a user who wants update notifications has to say so.

## Electron, React 19 and electron-vite, with pnpm pinned at 11

The stack is a conventional modern Electron application and the package manifest spells it out.

The main dependencies are Electron, React 19, TypeScript, and electron-vite as the build tool, with electron-store for local persistence and electron-builder for packaging. The package name is pawpal, the product name is PawPal, and the package manager field pins pnpm at 11.1.1, which is what the Corepack instructions are for.

The scripts show the workflow, and they are worth reading because the separation between them is the point:

```bash
pnpm test
pnpm build
pnpm dist
```

Under the hood, test runs node scripts/test.mjs, which is a plain Node script rather than a test framework runner, and the documentation describes the target as the pure logic tests. Build runs tsc --noEmit before electron-vite build, so type checking gates the bundle. The dist script runs the type check, the build, and then electron-builder for both mac and win, with dist:mac and dist:win available individually. The documentation notes that packaging on Windows needs Wine or a Windows machine.

The build configuration is where an Electron app's shipping decisions live, and several of them are visible here. The mac target produces a dmg for arm64 and x64. Hardened runtime is on, gatekeeperAssess is false, and notarize is true, with an entitlements plist and a matching inherit file. The Windows target is an NSIS installer for x64, configured as not one-click and with the installation directory changeable. The app id is com.pawpal.app, and the pet_assets directory is copied into the bundle as an extra resource, with .DS_Store filtered out.

## Running from source needs Node 24 and a working pnpm

The source build path is short, and the documentation is precise about the two prerequisites.

Source builds require Node.js 24+ and pnpm 11, with the version taken from the packageManager field in package.json. The recommended way to get pnpm is through Corepack:

```bash
corepack enable
git clone https://github.com/zebangeth/PawPal.git
cd PawPal
pnpm install
pnpm dev
```

There is a fallback for the common failure. If corepack enable does not have permission to install shims, the documentation says to install pnpm 11 another way and verify that pnpm --version works.

For packaging, there is a second prerequisite that is easy to miss. The documentation asks that you make sure the pnpm command is available directly in your shell before packaging locally, because electron-builder uses it while collecting dependencies. That is a specific and useful warning, because the failure would otherwise appear as an electron-builder error rather than as an obvious pnpm problem.

For end users, the alternative to building is downloading the installer from the Releases page, with a table naming the three files: PawPal-x.x.x-arm64.dmg for macOS Apple Silicon, PawPal-x.x.x-x64.dmg for macOS Intel, and PawPal.Setup.x.x.x.exe for 64-bit Windows.

So the same project supports two different audiences with two different installation paths, a packaged installer for people who want to use the app, and a source build for people who want to work on it.

## MIT for the code, a separate licence for the dog

The licence is split in two, and the split is documented rather than buried.

The source code is under the MIT License, with the LICENSE file at the repository root and the same field in the package manifest. The pet animation assets have their own separate licensing, and the documentation points to ASSET_LICENSE.md for that, with an ASSET_LICENSE.md file present in the repository root.

The distinction is worth understanding for a specific reason. The MIT code is the application logic, the window management, the reminders, the focus detection. The assets are the animations themselves, the GIFs in pet_assets/ that give the dog its movement and personality. Those may well come from a different source with different terms, and if you fork the project, redistribute the app, or build your own pet style on top, the two sets of terms apply independently.

Upkeep is modest but current. The last push was on 2026-08-11, the repository is not archived, and the tagged releases are v0.3.1 from 2026-06-02, v0.3.0 from 2026-05-07 and v0.2.0 from 2026-05-06. Three releases in about a month, and a version number under 0.4, which tells you this is an early-stage utility that people are still shaping.

The two-platform structure also shows in the repository layout, with a build/ directory holding the mac entitlements and the Windows icon, a scripts/ directory, a docs/ directory with the social preview image, and a pnpm-workspace.yaml alongside the lockfile.

## Conclusion

PawPal suits someone who wants a gentle, non-blocking prompt to step away from the screen and who is on macOS, since that is where the focus mode distraction detection works. It is the wrong choice for a Windows user who wants the focus mode, because the documentation states that feature is not yet available there, and the wrong choice if you need a serious wellbeing tool, since this is a reminder pet rather than a tracking system. Before installing, decide which installer you want, the Apple Silicon dmg or the Intel one, and read ASSET_LICENSE.md separately, because the pet animation assets are licensed apart from the MIT source code.

## FAQ

### Does the PawPal focus mode work on Windows?

No. The documentation states that the distraction detection feature is currently unavailable on Windows, since it is macOS only, while the other features work normally. Windows distraction detection is an unchecked item on the development roadmap, and focus mode on macOS requires granting Accessibility permission.

### Does PawPal send my usage data anywhere?

The documentation states that settings and statistics stay on your machine, and that PawPal only contacts GitHub Releases when you manually check for updates or opt in to launch-time checks. The storage layer is electron-store, which is local persistence.

### How do I run PawPal from source?

You need Node.js 24+ and pnpm 11, with pnpm 11 obtained through Corepack. Then run corepack enable, clone the repository, cd into it, and run pnpm install followed by pnpm dev. For packaging, the pnpm command must be available directly in your shell, because electron-builder uses it while collecting dependencies.

## Sources

- [Issues](https://github.com/zebangeth/PawPal/issues)
- [License: MIT](https://github.com/zebangeth/PawPal/blob/main/LICENSE)
- [README](https://github.com/zebangeth/PawPal/blob/main/README.md)
- [Releases](https://github.com/zebangeth/PawPal/releases)
- [zebangeth/PawPal on GitHub](https://github.com/zebangeth/PawPal)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zebangeth-pawpal