OpenPets isn’t just about cute animated pets on your desktop — it’s about how AI coding agents can autonomously link themselves to a desktop companion app through a layered, secure system. What caught my attention here is the architecture that lets agents install, configure, and communicate with their own sidecar pet via an IPC layer guarded by per-run tokens. It’s a neat example of self-instrumentation in AI tooling with privacy baked in.
How OpenPets integrates AI coding agents with a desktop companion
At its core, OpenPets is an Electron tray-first desktop app that adds an animated pet to your AI coding workflow. It’s built by Boring Dystopia Development and designed to work alongside AI agents like Claude Code and OpenCode. The pet isn’t just decoration; it reflects the agent’s state and reactions, providing a glanceable interface for agent observability.
Under the hood, the architecture consists of a three-layer integration stack:
MCP tools: These define explicit actions agents can take with the pet, such as speaking, reacting, or updating status. This provides a controlled API surface for agents to express their state and actions.
Managed agent instructions: These are sets of instructions guiding the agents on when and how to make use of MCP tools, ensuring agents use the pet companion appropriately within their workflows.
Hooks/plugins: These trigger automatic, decorative pet reactions tied to coding events like edits, tests, or permission requests, enhancing the interactive experience without explicit agent commands.
Communication flows from agents through packages like @open-pets/mcp or @open-pets/client to a local inter-process communication (IPC) socket hosted by the MCP server. This socket is protected by a discovery file containing a per-run token, which authenticates and scopes connections to the current session. This token-based IPC ensures secure, session-specific communication between agents and the desktop pet.
The stack uses TypeScript for agent integration libraries and Electron for the desktop app itself. Electron handles rendering the pet animations and tray icon, while the MCP server manages IPC communication and enforces token-based authentication.
A strong point is the privacy-conscious design. Speech bubbles displayed by the pet come from a static, local pool of messages. This means no prompts, code snippets, logs, secrets, or file paths are ever transmitted or exposed through the pet’s speech — everything stays local and sanitized.
What makes OpenPets’ architecture stand out
The standout feature is how the AI agents literally configure their own integration with the desktop pet. Rather than a fixed integration where the user manually sets up agent-to-desktop communication, OpenPets’ layered system lets agents install MCP tools, apply managed instructions, and enable hooks/plugins autonomously. This self-instrumentation pattern is rare and worth understanding.
The tradeoff here is complexity versus flexibility. The multi-layer approach provides a clear separation of concerns: agents have explicit APIs (MCP tools), behavioral guidance (instructions), and ambient reactions (hooks/plugins). This makes the system extensible and modular but requires careful orchestration.
The code quality appears solid, with the use of modern TypeScript patterns and modular packages such as @open-pets/mcp, @open-pets/client, and pet-pack systems. By keeping the IPC communication local and token-protected, it avoids common pitfalls around unauthorized access and session leakage.
On the UX side, the pet animations and tray integration are unobtrusive yet informative, providing glanceable feedback without overwhelming the developer. The decision to restrict speech bubbles to non-sensitive static messages is a pragmatic privacy tradeoff that avoids leaking context or secrets.
In practice, this means OpenPets is more than a novelty; it’s a lightweight sidecar observability layer for AI coding agents that respects privacy and security.
Quick start
The README provides a straightforward quick start to get OpenPets running with your coding agents.
First, install the OpenPets Agent Skill using npx:
npx skills add alvinunreal/openpets --skill openpets
Then, within Claude Code, OpenCode, Codex, or another skill-aware agent, you can say:
Use the OpenPets skill. Install OpenPets for me, connect this agent, and verify the integration works.
For project-specific 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.
There are helpful prompts for configuring with Claude Code or OpenCode, debugging status availability, and more.
You can also install the desktop app directly from the releases page. Available builds cover macOS (Apple Silicon and Intel), Windows, and Linux:
- 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
Once installed, launch the app to see the pet and tray icon. For macOS, you might need to remove the quarantine flag if you see security warnings:
xattr -dr com.apple.quarantine /Applications/OpenPets.app
open /Applications/OpenPets.app
From the desktop app’s Integrations screen, you can connect to Claude Code or OpenCode for global setup. For local project setup, the CLI offers commands like:
npx -y @open-pets/cli@latest configure --agent claude --pet <petID>
This installs MCP, relevant instruction files, and plugins for your project.
who should consider using OpenPets
OpenPets is relevant for developers working with AI coding agents like Claude Code and OpenCode who want a lightweight, privacy-conscious companion app that provides glanceable agent observability without exposing sensitive data.
The architecture’s self-instrumenting integration is a neat pattern to study if you’re building extensions that require secure local IPC and autonomous configuration by AI agents.
Limitations include the focus on desktop environments (Electron app), so it’s not suitable for purely web-based workflows. Also, the static message pool for speech bubbles sacrifices some expressiveness for privacy, which might not suit all use cases.
Overall, OpenPets offers a solid balance of usability, security, and architectural elegance for AI agent sidecar integration. It’s worth exploring if you want a pet that’s more than skin deep.
→ GitHub Repo: alvinunreal/openpets ⭐ 906 · TypeScript