OpenPets

A tiny desktop pet for coding agents.

See agent progress, tool use, test runs, and coding state as a playful desktop companion.

---

What is OpenPets?

OpenPets is a tray-first desktop companion app for AI coding agents.

• Desktop companion — a small pet that reacts while agents think, edit, test, wait for approval, finish, or hit an error.
• Agent integrations — first-class setup for Claude Code and OpenCode, including MCP tools, instructions, and automatic hooks/plugins.
• MCP ready — any MCP-capable agent can send short safe speech bubbles and reactions through the OpenPets MCP server.
• 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.

The current v2 workspace lives in apps/* and packages/*. The v1/ folder is reference material only, and web/ remains outside the v2 workspace.

Quick start

Install the desktop app, then 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. 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.

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

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

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.

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 openpets configure --agent claude --pet <petId>.

Typical global MCP command shape:

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

With a selected pet:

claude mcp add --scope user openpets -- npx -y @open-pets/mcp --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 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"]
    }
  }
}

To target a specific installed non-default pet:

{
  "mcpServers": {
    "openpets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@open-pets/mcp", "--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_say messages must be short, single-line, and must not look like code, logs, secrets, URLs, or file paths.

How it works

Claude Code / OpenCode / MCP client
  -> @open-pets/mcp, @open-pets/cli mcp, @open-pets/claude hook, or @open-pets/opencode plugin
  -> @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.

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.

Development

Requirements

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

No Bun runtime is required for v2 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/agent-events     Shared safe agent event speech helpers
packages/cli              @open-pets/cli, user-run CLI and MCP/hook entrypoints
packages/pet-format       @open-pets/pet-format, pet/catalog format types
docs/                     Current v2 documentation
v1/                       Historical/reference material only
web/                      Existing web app, outside the v2 workspace

Documentation

• docs/claude-integration.md — Claude Code setup, MCP, memory, hooks, and safety.
• docs/opencode.md — OpenCode global/project setup, plugin behavior, and safety.
• 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.