https://github.com/alvinunreal/openpets
Desktop pets for AI coding agents. Install pets, connect Claude Code via MCP, and see live coding status on your desktop.
https://github.com/alvinunreal/openpets
ai-agents bun claude-code coding-agents desktop-pet electron mcp opencode openpets pixel-art
Last synced: 2 days ago
JSON representation
Desktop pets for AI coding agents. Install pets, connect Claude Code via MCP, and see live coding status on your desktop.
- Host: GitHub
- URL: https://github.com/alvinunreal/openpets
- Owner: alvinunreal
- License: mit
- Created: 2026-05-04T19:14:46.000Z (27 days ago)
- Default Branch: main
- Last Pushed: 2026-05-27T13:13:37.000Z (5 days ago)
- Last Synced: 2026-05-27T14:17:44.955Z (4 days ago)
- Topics: ai-agents, bun, claude-code, coding-agents, desktop-pet, electron, mcp, opencode, openpets, pixel-art
- Language: TypeScript
- Homepage: https://openpets.dev
- Size: 30.1 MB
- Stars: 948
- Watchers: 1
- Forks: 32
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome - alvinunreal/openpets - Desktop pets for AI coding agents. Install pets, connect Claude Code via MCP, and see live coding status on your desktop. (TypeScript)
README
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.
by Boring Dystopia Development
---
## 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.
## 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.
- **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](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.
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_say` messages must be short, single-line, and must not look like code, logs, secrets, URLs, or file paths.
## 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 and MCP/hook entrypoints
packages/pet-format @open-pets/pet-format, pet/catalog format types
docs/ Documentation
```
## Documentation
- [`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.