A desktop companion platform with pets, plugins, and optional local agent integrations.

OpenPets puts an animated companion on your desktop, then lets plugins turn it into a focus buddy, reminder system, tiny game, launcher, or coding-agent sidekick.

Read this in: English | 日本語 | 한국어 | 简体中文 | 繁體中文 | Português (Brasil) | Español (LatAm)

Download the latest OpenPets desktop release and launch it. A pet appears immediately; no agent setup required.

• Desktop pets: animated companions that idle, wander, react, and keep your workspace from feeling empty.
• Official plugins: focus timers, reminders, mood check-ins, mini games, launch shortcuts, hydration nudges, and virtual-pet stats.
• Plugin SDK v3: a sandboxed JavaScript/TypeScript runtime for building new pet abilities with permissions, quotas, storage, schedules, commands, panels, events, audio, notifications, and more.
• Optional agent layer: Claude Code, OpenCode, Cursor, Pi, and MCP clients can drive local pet reactions without exposing prompts, code, paths, logs, or secrets in speech bubbles.

If OpenPets makes your coding setup or desktop workspace a little more fun, please give the repo a star.

You do not need to be a developer or connect any AI agents to enjoy OpenPets. The desktop app is fully functional out of the box with the official plugin lineup.

Download the package for your operating system from OpenPets Releases:

• macOS Apple Silicon: OpenPets-*-mac-arm64.dmg
• macOS Intel: OpenPets-*-mac-x64.dmg
• Windows: OpenPets-*-win-x64-setup.exe
• Linux: OpenPets-*-linux-x86_64.AppImage

Note: Current builds may be unsigned. If macOS blocks execution with a security warning, remove the quarantine flag via terminal:

xattr -dr com.apple.quarantine /Applications/OpenPets.app

Browse installed pets, preview their animation frames, and configure which pet monitors each workspace or agent window from the built-in Pet Gallery.

OpenPets v3 ships with a modular Official Plugin Catalog. Enable or configure plugins via the desktop Control Center to add focus timers, reminders, and mini interactive games.

• Day Routine: Tracks habits and reminds you to stretch or step away.
• Focus Buddy: Pomodoro-style focus timers to manage work cycles.
• Fortune Cookie: Cracks open randomized daily advice and wisdom.
• Launch Buddy: Allows registering shortcut commands to quickly open local folders, projects, or applications.
• Magic 8 Ball: Ask questions and receive playful, randomized answers from your pet.
• Mood Check-in: Periodically checks in on your mood to support emotional well-being.
• Reminders: Renders snoozeable, bell-alert notifications with custom audio tones.
• Virtual Pet: Turns your desktop companion into a Tamagotchi-style pet with hunger, affection, and energy levels tracked via a live status pin.
• Water Reminder: Keeps you hydrated with regular, customizable drinking prompts.

The OpenPets plugin system offers a secure, developer-friendly SDK (@open-pets/plugin-sdk) for creating custom companion behavior.

• Sandboxed Runtime: Each JS plugin runs inside a sandboxed BrowserWindow host environment.
• Host-Rendered UI: Plugins describe actions, HUDs, and notifications; the desktop host renders them. HTML/JS code cannot render raw HTML or execute arbitrary scripting inside a pet window.
• Permissions Model: Permissions must be declared in the manifest and approved by the user at install. Flagged sensitive APIs (like voice:listen, clipboard, and pet:speak:dynamic) require explicit consent toggles.
• SSRF & Private Host Guards: Network fetch requests are limited to developer-declared hostnames and guarded against local SSRF.

Plugins hook into the desktop environment via the ctx object, exposing:

• ctx.pets / ctx.pet: Manage default and spawned pet instances: spawn, move, animate, and react.
• ctx.ui: Alerts, transient/pinned bubbles, custom menus, panels, and status HUDs. Pinned mini HUD bubbles support compact 2x2 grid layouts with progress bars, such as Virtual Pet stats.
• ctx.audio: Trigger host-managed alert tones or user-imported custom audio.
• ctx.schedule: Set precise timer hooks (once, every, daily, cron, at).
• ctx.ai / ctx.secrets: Hook into the user's host-configured AI provider (Anthropic, OpenAI, Ollama) without exposing API keys to the plugin source.
• ctx.storage: Simple JSON key-value store with change subscriptions.
• Other APIs: events, assets, bus, net (with streaming support), notify, voice (TTS & push-to-talk STT), auth (PKCE browser flow), files (secure picked OS dialogs), system, commands, status, and log.

Create, validate, and test plugins using the official CLI.

Create a template from any of the official layouts (blank, reminder, ambient, ai-chat, tamagotchi, calendar):

npx @open-pets/cli plugin new "My Plugin" --template tamagotchi

Verify manifest layout, permissions, and configuration schemas before packing:

npx @open-pets/cli plugin validate ./my-plugin

Write deterministic tests without launching the desktop app. Using @open-pets/plugin-sdk/testing's createTestHarness, you can mock the host, advance clocks, trigger actions, and verify reactions:

import { createTestHarness } from "@open-pets/plugin-sdk/testing";
import { register } from "./index.js";

const h = createTestHarness(register, { permissions: ["pet:speak", "schedule"] });
await h.start();
h.expectScheduled("decay");
await h.clock.advance("30m");
h.expectSpoke(/need attention/i);

Run plugin tests from your plugin project:

npm test

If you want your development agent to drive your desktop companion, OpenPets provides an optional local MCP (Model Context Protocol) integration layer.

When you configure an agent, OpenPets exposes standard MCP tools. The agent can trigger animations, change status, and display text bubbles locally:

1. Claude Code: Installs OpenPets MCP, memory instructions in ~/.claude/CLAUDE.md, and hooks in ~/.claude/settings.json.
2. OpenCode: Installs OpenPets MCP, custom project instruction files, and the @open-pets/opencode automatic hook plugin.
3. Cursor / Other MCP Clients: Register OpenPets as a standard stdio or TCP MCP server.

To run OpenPets as an MCP tool, add the server to your agent's configuration:

{
  "mcpServers": {
    "openpets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@open-pets/mcp@latest"]
    }
  }
}

Tip: To target a specific pet, pass the --pet <petId> argument.

• openpets_status: Retrieve target pet ID and check runtime connectivity.
• openpets_react: Set pet reaction animations (e.g., thinking, editing, testing, success, error).
• openpets_say: Display a short speech bubble.

• All automated reactions run on static local triggers (e.g., when a command runs or a file is written).
• Speech content is validated to prevent leaking sensitive variables, paths, secrets, or multiline code snippets.
• Real-time interaction requires a local discovery token write/read, protecting the IPC bridge from external network triggers.

For contributing to the OpenPets codebase, testing changes, or building the desktop packages locally.

• Node.js: version 20 or higher
• pnpm: version 11 or higher
• TypeScript: compiler support

Install project workspace dependencies:

pnpm install

Launch the Electron application in local developer mode:

pnpm dev:desktop

Launch with live official plugins loaded and monitored:

pnpm dev:desktop:plugins

Run workspace typechecking, code-conformance validations, and tests:

pnpm check
pnpm typecheck
pnpm test

Package the desktop application:

# Build & package into target OS directory
pnpm package:desktop:dir

# Build & package into final installer / setup archives
pnpm package:desktop

apps/desktop              Electron desktop application
packages/client           @open-pets/client (IPC helper library)
packages/mcp              @open-pets/mcp (Model Context Protocol stdio server)
packages/claude           @open-pets/claude (Claude integrations, memory, & hooks)
packages/opencode         @open-pets/opencode (OpenCode plugins & instruction configs)
packages/pi               @open-pets/pi (Pi CLI extension integration)
packages/agent-events     Shared sanitizers and events helper package
packages/cli              @open-pets/cli (User entry point CLI for configuration & scaffolding)
packages/sdk              @open-pets/plugin-sdk (Plugin SDK v3 declarations & testing harness)
packages/pet-format       @open-pets/pet-format (Pet manifest and schema types)
plugins/official          Official first-party plugin workspace (bundled with host catalog)
docs/                     Technical specifications and architecture documentation

Explore detailed architectural and platform documentation inside the docs/ folder:

• docs/plugins.md - Plugin platform SDK v3 manifest, permissions, and testing kit.
• docs/claude-integration.md - Integrating with Claude Code (memory, hooks, MCP).
• docs/opencode.md - Integrating with OpenCode workspaces.
• docs/wsl-ipc.md - Setting up the WSL-to-Windows TCP bridge.
• docs/testing.md - Workspace test and conformance strategy.
• docs/release.md - Application packaging and release processes.
• docs/workflow.md - Core development and contributions workflow.

• Local-Only: OpenPets IPC works using a local socket/named pipe, secured with a per-run random security token.
• SSRF Safety: Plugin network connections are restricted to approved domains and blocked from local network/private IP access.
• Dynamic Content Sanitization: Any dynamic AI-speech text runs through strict local filters to redact paths, URLs, secrets, or multiline code snippets.
• Sensitive Permission Consent: Features accessing clipboard, microphone, or dynamic AI responses are off by default and require explicit user opt-in.