Global Pet Assistant

A local-first macOS desktop pet that turns coding-agent, terminal, and build events into a tiny companion on your screen.

中文 · Docs · Integrations · Download

Global Pet Assistant is a native AppKit utility for people who live in local developer tools. It renders a transparent always-on-top pet, accepts local events from trusted integrations, and turns those events into animations, quick status flashes, and persistent agent-thread reminders.

The app is intentionally small: no hosted account, no cloud relay, no network webhook listener by default. Your tools talk to a local server on 127.0.0.1, protected by a local bearer token.

Highlights

Area	What you get
Native desktop pet	Transparent AppKit window, drag-to-move, edge snapping, resizing, menu bar controls, and smooth spritesheet animation.
Coding-agent status	Codex hook support for running, waiting-for-approval, completed, and review states.
Terminal feedback	Kitty watcher plugin for command start/end flashes without editing shell startup files.
Local event API	petctl and localhost HTTP event ingestion for scripts, builds, and local tools.
Persistent reminders	Longer-lived thread panel items stay visible until dismissed instead of disappearing like toast notifications.
Conservative actions	Notification clicks can open allowlisted apps, URLs, files, folders, or supported terminal/session targets.
Pet packages	Codex-compatible 1536x1872 spritesheet packages can be imported into the app-owned pet directory.

Install

Download the latest DMG from GitHub Releases, open it, and drag GlobalPetAssistant.app into /Applications. Launch the app once, then run the bundled setup guide:

open /Applications/GlobalPetAssistant.app
/Applications/GlobalPetAssistant.app/Contents/Resources/Tools/setup-integrations.sh

The DMG install only copies the app. The setup guide shows every external config file it may modify, creates backups, and lets you choose integrations such as Kitty command flashes and Codex session reminders.

The current beta is not notarized yet. If macOS blocks first launch, open the app from Finder with Control-click -> Open, or allow it from System Settings. See Integration Setup for manual and non-interactive commands.

How It Works

Local tools / agents / terminal plugins
        |
        v
petctl, Codex hooks, Kitty watcher, localhost HTTP
        |
        v
Local event router + action allowlist
        |
        v
Pet animation, flash message, or thread reminder

Global Pet Assistant keeps runtime state under ~/.global-pet-assistant:

Path	Purpose
~/.global-pet-assistant/token	Local bearer token for event writes.
~/.global-pet-assistant/config.json	Source allowlist, pet import paths, and runtime preferences.
~/.global-pet-assistant/logs/	Runtime, event, and hook logs.
~/.global-pet-assistant/pets/	Imported or bundled pet packages.

Documentation

Start here:

• Documentation Hub: install, integration, architecture, and maintainer map.
• Integration Setup: Kitty plugin and Codex hooks.
• Architecture: renderer, event API, action model, and local security boundary.
• Assets and Licensing: app icon and pet asset rules.
• Security Policy: local event server, tokens, logs, and vulnerability reporting.
• Contributing: development workflow and pull request expectations.

Develop

Requirements:

• macOS 26 SDK or newer for the current AppKit surface.
• Swift 6.2 or newer.
• Xcode Command Line Tools.

swift build
swift test
Tools/package-debug-app.sh
open .build/GlobalPetAssistant.app

Runtime smoke checks:

swift run GlobalPetAssistant
Tools/verify-event-runtime.sh

Tools/verify-event-runtime.sh launches the app itself. Stop any already running copy first if port 17321 is busy.

Privacy

Global Pet Assistant is local-first:

• The event server binds to 127.0.0.1.
• Event writes require Authorization: Bearer <token>.
• No hosted account or cloud telemetry is required.
• Unknown sources may send state notifications, but cannot open apps, URLs, files, folders, or terminal windows.

See Privacy and Security Policy for the precise runtime model.

Uninstall

Quit the app, remove the bundle, and optionally remove app-owned state:

rm -rf /Applications/GlobalPetAssistant.app
rm -rf ~/.global-pet-assistant

If you installed integrations, also remove their managed config:

/Applications/GlobalPetAssistant.app/Contents/Resources/bin/petctl uninstall kitty,codex

See Integration Setup for per-module cleanup.