A tiny desktop companion that keeps you company.

A playful pet that lives on your desktop, keeps you company, and can grow with bundled abilities and developer integrations.

_{This branch also includes a floating chat surface, local memory, vanilla MCP tools, and expanded pet sizing. See FEATURES.md and PULL_REQUEST.md for details.}

_{by Boring Dystopia Development}

     

---

2-minute Quick Start

Download and launch the desktop app from OpenPets Releases. A companion pet appears immediately; bundled abilities make it feel alive without requiring an agent setup.

If you also want coding-agent integration, install the OpenPets Agent Skill with skills.sh:

npx skills add alvinunreal/openpets --skill openpets

Then open Claude Code, OpenCode, Codex, or another skill-aware agent and say:

Use the OpenPets skill. Install OpenPets for me, connect this agent, and verify the integration works.

For project setup, open your agent inside the repo and say:

Use the OpenPets skill. Help me choose or install a pet, configure it for this project, and verify the project integration.

Useful prompts:

Use the OpenPets skill. Configure this project for Claude Code with a pet.
Use the OpenPets skill. Configure this project for OpenCode with a pet.
Use the OpenPets skill. Debug why openpets_status is unavailable.

Star OpenPets

Here is an extra GIF of me starring my own repo to encourage you to do the same. If OpenPets makes your coding setup a little more fun, please give the repo a star.

What is OpenPets?

OpenPets is a tray-first desktop companion app. A pet appears on your desktop, keeps you company, and can use bundled abilities for ambient presence, breaks, playful actions, and focus sessions. Coding-agent integrations are still supported as an advanced developer layer.

• Desktop companion - a small pet that idles, reacts, and gives OpenPets a friendly presence even before developer tools are configured.
• Bundled abilities - first-party plugins can add ambient check-ins, break nudges, playful pet actions, focus timers, safe little walks, and optional developer notifications.
• Developer integrations - advanced setup for Claude Code, OpenCode, Cursor, Pi, and MCP-capable tools when you want coding activity to drive the pet.
• MCP ready - any MCP-capable agent can send short safe speech bubbles and reactions through the OpenPets MCP server.
• Floating chat - double-click the pet to open an always-on-top chat window with BYOK OpenAPI-compatible providers, conversation history, and optional MCP tool activation.
• Virtual-pet status - triple-click the pet to briefly show hunger, energy, happiness, and bond bars; the HUD auto-hides so it never interferes with chat.
• Local memory - the pet remembers facts, preferences, and notes across sessions.
• Pet-pack friendly - loads installed animated pet packs and can route a selected agent/project to its own pet window.
• Privacy-conscious by design - automatic hook speech is static and local; prompts, code, logs, command output, URLs, paths, and secrets are not shown in bubbles.

Manage your pets

Browse installed pets, preview their animations, and choose which companion should follow each coding agent from the OpenPets desktop app.

Quick start

Install the desktop app, then optionally connect your coding agent.

1. Install OpenPets Desktop

Download the latest app 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

Launch OpenPets. You should see the desktop pet and the OpenPets tray/menu-bar icon.

Current builds may be unsigned. macOS or Windows may show a security warning the first time you open the app.

If macOS says the app is damaged or should be moved to Trash, remove the quarantine flag and open it again:

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

2. Optional: connect your agent

Use the desktop Integrations screen for global setup when available:

• Claude Code - installs OpenPets MCP, Claude memory instructions, and optional Claude hooks.
• OpenCode - installs OpenPets MCP, an OpenCode instruction file, and the @open-pets/opencode plugin.
• MCP Toolkit - curated setup guidance for Filesystem, Git, GitHub, Playwright, Browser Use, Memory, Fetch, Docker, and adjacent terminal/system MCP layers.

For project-local setup, run the CLI from the project you want to configure:

npx -y @open-pets/cli@latest configure --agent claude --pet <petId>
npx -y @open-pets/cli@latest configure --agent opencode --pet <petId>

If you prefer a permanent openpets shell command, install the CLI once with npm install -g @open-pets/cli and replace npx -y @open-pets/cli@latest with openpets.

Project-local setup can create project files such as .claude/settings.local.json or .opencode/opencode.jsonc. Review them before committing because they may include the selected pet id.

Advanced: agent integrations

OpenPets integrations have three layers:

1. MCP tools for explicit agent actions.
2. Agent instructions so agents know when to use those tools.
3. Hooks/plugins for automatic decorative reactions during normal agent work.

Claude Code

Claude Code integration supports:

• openpets MCP setup via Claude Code.
• Managed Claude memory instructions in ~/.claude/CLAUDE.md and ~/.claude/openpets.md.
• Managed Claude hooks in ~/.claude/settings.json.
• Project-local setup through npx -y @open-pets/cli@latest configure --agent claude --pet <petId> or the optional global openpets CLI.

Typical global MCP command shape:

claude mcp add --scope user openpets -- npx -y @open-pets/mcp@latest

With a selected pet:

claude mcp add --scope user openpets -- npx -y @open-pets/mcp@latest --pet <petId>

See docs/claude-integration.md for the full file layout, hook mapping, project-local behavior, and safety rules.

OpenCode

OpenCode integration supports:

• An MCP entry using @open-pets/cli mcp.
• A managed openpets.md instruction file.
• The @open-pets/opencode plugin for automatic reactions.
• Global desktop setup and project-local .opencode setup.

Project-local setup:

npx -y @open-pets/cli@latest configure --agent opencode --pet <petId>

See docs/opencode.md for global config selection, plugin behavior, project-local setup, and safety rules.

Generic MCP clients

Any MCP-capable editor or coding agent can talk to OpenPets through the MCP server while the desktop app is running.

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

To target a specific installed non-default pet:

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

Available MCP tools:

• openpets_status - check whether OpenPets is reachable and which pet is targeted.
• openpets_react - set a short reaction on the target pet.
• openpets_say - show a short safe speech bubble, optionally with a reaction.
• openpets_memory_list - list recent long-term memories stored by OpenPets.
• openpets_memory_search - search pet memory for relevant facts, preferences, or notes.
• openpets_memory_store - store a durable memory for the pet.
• openpets_memory_forget - delete a stored memory by id.

openpets_say messages must be short, single-line, and must not look like code, logs, secrets, URLs, or file paths.

Curated MCP toolkit

The desktop app also includes a manual-but-curated MCP Toolkit panel under Integrations. It is there to help you build a practical broader stack without stuffing OpenPets full of unsafe one-click third-party installs.

The toolkit now explicitly offers two paths:

• Manual Setup - per-tool guidance, docs links, and copyable snippets
• Persistent Full Access - Install Now for the supported persistent baseline in hosts such as Claude Code or Codex CLI, plus a matching copyable bundle
• Vanilla Chat Tools - activate MCP tools directly inside the floating chat window for autonomous filesystem, terminal, web, and browser tasks

The current supported Install Now baseline covers:

• Filesystem
• Playwright
• Memory
• Context7 / Docs
• Fetch / Web when uvx is available
• Sequential Thinking
• Browser Use when uvx is available, with its own runtime credential still required

The current recommended starter set is:

• Filesystem
• Git
• GitHub
• Playwright
• Browser Use
• SQLite / PostgreSQL
• Memory
• Fetch / Web
• Sequential Thinking
• Docker MCP Toolkit

It also maps the next terminal-oriented layers that usually matter once your workflow grows up a bit:

• Shell / Terminal
• Process & Logs
• System Info
• SSH
• Package Manager
• Tmux
• Kubernetes / Cloud
• CI / CD
• Ghidra
• Binary Analysis
• Network Analysis

How it works

Claude Code / OpenCode / Pi / MCP client
  -> @open-pets/mcp, @open-pets/cli mcp, @open-pets/claude hook, @open-pets/opencode plugin, or @open-pets/pi extension
  -> @open-pets/client
  -> OpenPets desktop local IPC discovery file
  -> OpenPets desktop IPC socket/pipe
  -> default pet or selected agent pet window

The desktop app writes a local discovery file containing an IPC endpoint and a per-run token. Clients must send that token with every request.

For Windows desktop + WSL agent setups, see docs/wsl-ipc.md for the opt-in TCP transport.

When an integration is configured with --pet <petId>, OpenPets asks the desktop app for a short-lived lease. Valid installed non-default pets open as explicit agent pet windows. Missing, invalid, broken, built-in, or default pet requests fall back to the desktop default pet.

Reactions and speech

Automatic hooks are decorative and best-effort. They do not approve, deny, block, or change agent behavior.

Common reaction mapping:

Agent activity	Reaction
Prompt/chat starts	thinking
File edit/write/patch	editing
Test-like shell command	testing
Permission request	waiting
Successful idle/stop	success
Session/error stop	error

Generic shell activity is intentionally quiet by default. Hook/plugin speech is throttled and selected from local static message pools such as Approval needed or Something failed.

Pi extension package

OpenPets includes an experimental Pi extension package at @open-pets/pi. Pi support is extension-first rather than MCP-first: the extension listens to Pi lifecycle/tool events and sends local best-effort reactions through @open-pets/client.

pi install npm:@open-pets/pi
pi install -l npm:@open-pets/pi

Inside Pi, the extension registers /openpets status, /openpets test, /openpets react <reaction>, and /openpets say <message>. Automatic events do not forward prompts, assistant text, tool output, file contents, paths, URLs, or secrets. Real Pi CLI install validation is still required before marking the integration fully supported.

Development

Requirements

• Node.js 20+
• pnpm 11+
• TypeScript

No Bun runtime is required for development.

Install

pnpm install

Run the desktop app

pnpm dev:desktop

Equivalent package command:

pnpm --filter @open-pets/desktop dev

Checks

pnpm check
pnpm typecheck
pnpm build
pnpm test

OpenPets currently uses lightweight Node contract checks instead of a full test framework. See docs/testing.md.

Package desktop builds

pnpm package:desktop:dir
pnpm package:desktop

Release process details live in docs/release.md.

Workspace layout

apps/desktop              Electron desktop app
packages/client           @open-pets/client, local IPC client
packages/mcp              @open-pets/mcp, MCP stdio server
packages/claude           @open-pets/claude, Claude command and hook helpers
packages/opencode         @open-pets/opencode, OpenCode config and plugin integration
packages/pi               @open-pets/pi, Pi extension package
packages/agent-events     Shared safe agent event speech helpers
packages/cli              @open-pets/cli, user-run CLI, plugin scaffolder/validator, MCP/hook entrypoints
packages/sdk              @open-pets/plugin-sdk, plugin SDK v3 types + testing harness
packages/pet-format       @open-pets/pet-format, pet/catalog format types
plugins/official          First-party plugin source (bundled + catalog)
docs/                     Documentation

Documentation

• docs/plugins.md - plugin platform (SDK v3): manifest, permissions, dev workflow, test kit.
• docs/superplugins.md - SDK v3 design rationale and feature spec.
• docs/claude-integration.md - Claude Code setup, MCP, memory, hooks, and safety.
• docs/opencode.md - OpenCode global/project setup, plugin behavior, and safety.
• docs/wsl-ipc.md - Windows desktop + WSL MCP transport setup.
• docs/testing.md - test/check strategy.
• docs/release.md - desktop release process.
• docs/workflow.md - project workflow notes.

Safety and privacy notes

• OpenPets local IPC is local-only and protected by a per-run token.
• Hook/plugin errors are swallowed unless debug logging is enabled.
• Automatic speech is static and local; it does not include model-generated prompt text.
• Tool inputs and command text are used only for coarse reaction classification.
• Managed setup preserves unrelated user config and removes only OpenPets-managed entries.
• Speech validation rejects code-like, secret-like, URL-like, path-like, or multiline messages.