OpenPets - pixel art desktop companion

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.

OpenPets reacting across multiple coding agent sessions

by Boring Dystopia Development

boringdystopia.ai  X @alvinunreal  Telegram Join channel 

--- ## 2-minute Quick Start Download and launch the desktop app from [OpenPets Releases](https://github.com/alvinunreal/openpets/releases/latest). 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](https://skills.sh/): ```bash npx skills add alvinunreal/openpets --skill openpets ``` Then open Claude Code, OpenCode, Codex, or another skill-aware agent and say: ```text 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: ```text Use the OpenPets skill. Help me choose or install a pet, configure it for this project, and verify the project integration. ``` Useful prompts: ```text 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.

Starring the OpenPets repository

## 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.

Managing pets in 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](https://github.com/alvinunreal/openpets/releases/latest): - **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: ```bash 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.

OpenPets desktop integrations screen

For project-local setup, run the CLI from the project you want to configure: ```bash npx -y @open-pets/cli@latest configure --agent claude --pet npx -y @open-pets/cli@latest configure --agent opencode --pet ``` 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 ` or the optional global `openpets` CLI. Typical global MCP command shape: ```bash claude mcp add --scope user openpets -- npx -y @open-pets/mcp@latest ``` With a selected pet: ```bash claude mcp add --scope user openpets -- npx -y @open-pets/mcp@latest --pet ``` See [`docs/claude-integration.md`](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: ```bash npx -y @open-pets/cli@latest configure --agent opencode --pet ``` See [`docs/opencode.md`](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. ```json { "mcpServers": { "openpets": { "type": "stdio", "command": "npx", "args": ["-y", "@open-pets/mcp@latest"] } } } ``` To target a specific installed non-default pet: ```json { "mcpServers": { "openpets": { "type": "stdio", "command": "npx", "args": ["-y", "@open-pets/mcp@latest", "--pet", ""] } } } ``` 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 ```text 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`](docs/wsl-ipc.md) for the opt-in TCP transport. When an integration is configured with `--pet `, 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`. ```bash pi install npm:@open-pets/pi pi install -l npm:@open-pets/pi ``` Inside Pi, the extension registers `/openpets status`, `/openpets test`, `/openpets react `, and `/openpets say `. 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 ```bash pnpm install ``` ### Run the desktop app ```bash pnpm dev:desktop ``` Equivalent package command: ```bash pnpm --filter @open-pets/desktop dev ``` ### Checks ```bash 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`](docs/testing.md). ### Package desktop builds ```bash pnpm package:desktop:dir pnpm package:desktop ``` Release process details live in [`docs/release.md`](docs/release.md). ## Workspace layout ```text 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`](docs/plugins.md) - plugin platform (SDK v3): manifest, permissions, dev workflow, test kit. - [`docs/superplugins.md`](docs/superplugins.md) - SDK v3 design rationale and feature spec. - [`docs/claude-integration.md`](docs/claude-integration.md) - Claude Code setup, MCP, memory, hooks, and safety. - [`docs/opencode.md`](docs/opencode.md) - OpenCode global/project setup, plugin behavior, and safety. - [`docs/wsl-ipc.md`](docs/wsl-ipc.md) - Windows desktop + WSL MCP transport setup. - [`docs/testing.md`](docs/testing.md) - test/check strategy. - [`docs/release.md`](docs/release.md) - desktop release process. - [`docs/workflow.md`](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.