DOCSEARCHbyAlgolia
Submit Docs

OpenPets Documentation

repository·main·Indexed 21 days ago

https://github.com/alvinunreal/openpets

A desktop companion platform featuring animated pets and a plugin system to create workspace tools or AI agent sidekicks. Includes documentation for the @open-pets/plugin-sdk for building plugins using the OpenPetsPlugin global and OpenPetsContext API, as well as guides for community plugins like Drag Vocab, Higgsfield Watch, Spotify Buddy, and Walkabout.

Tokens
107.1K
Snippets
276
Records
521
Agent score
75%

What's inside OpenPets

  1. Overview of OpenPets Desktop Companion

    main

    OpenPets Desktop is a tray-first Electron application designed to provide animated desktop pets that react to coding agent events. It serves as a central hub for managing pet installations, configuring the React/Tailwind-based Control Center, managing plugin automation/runtimes, and integrating with coding agents like Claude Code, OpenCode, Cursor, and Pi.

    Key Features:

    • Tray-First UX: The app operates primarily from the system tray; the main Control Center window is a singleton opened via tray actions.
    • Pet Types: Supports a persistent Default Pet, and transient Agent Pets that appear via lease-based routing when requested by coding agents.
    • Plugin System: A robust subsystem for both declarative manifest-based plugins and JavaScript-based plugins with sandboxed execution and permission management.
    • Agent Integration: Automatically detects and configures CLI tools and MCP (Model Context Protocol) settings for popular coding agents.

  2. Overview of OpenCode package structure

    main
    The opencode package provides the core logic for OpenCode integration within the OpenPets ecosystem. It includes modules for plugin definitions, runtime hook implementations, configuration management, project and global setup, status classification, and configuration entry builders. The package uses a barrel export in index.ts to re-export all public modules.

  3. Overview of OpenPets npm packages

    main

    OpenPets is a monorepo containing modular, reusable components for the OpenPets ecosystem. All packages are ESM-first ("type": "module") and follow a consistent structure with TypeScript source in src/, compiled output in dist/, and runtime contract validation in contracts/.

    Core Packages

    • @open-pets/client: The core IPC client used to communicate with the OpenPets desktop app via Unix sockets, Windows named pipes, or TCP.
    • @open-pets/cli: The main command-line tool for configuring agents, managing pets, launching MCP servers, and scaffolding plugins.
    • @open-pets/mcp: An MCP (Model Context Protocol) stdio server implementation that registers tools like status, react, and say.
    • @open-pets/sdk: Provides the public SDK v3 type definitions and a deterministic testing harness for plugin authors.
    • @open-pets/agent-events: Contains speech pools and validation for agent feedback messages.
    • @open-pets/pet-format: A package marker interface used for type identification.

    Editor & Agent Integrations

    • @open-pets/claude: Integration for Claude Code (hooks and config management).
    • @open-pets/cursor: Integration for Cursor editor (MCP configuration and project rules).
    • @open-pets/opencode: Integration for OpenCode editor (plugin hooks and config management).
    • @open-pets/pi: Integration for the Pi coding-agent extension (event handling and slash commands).

    Other Utilities

    • install-pet: A standalone installer for pets from the gallery catalog.

  4. Overview of the OpenPets MCP Server

    main
    The OpenPets MCP (Model Context Protocol) server allows AI agents to interact with OpenPets functionality. It exposes specific tools that enable an agent to check the status of a pet, set reactions, and display messages on the desktop pet via the Model Context Protocol.

  5. Use @open-pets/cli for agent and plugin management

    main
    The @open-pets/cli is the primary developer tool for managing OpenPets agent configurations and pet assets. It allows you to configure integrations for editors like Claude, OpenCode, and Cursor, manage pet installations, and scaffold new plugins using the SDK v3.

  6. Understand the OpenCode editor integration

    main

    OpenCode is an editor integration for OpenPets that provides a bridge between the OpenPets agent and your coding environment. It manages MCP (Model Context Protocol) server configurations, provides a plugin runtime with event hooks, and handles the setup/removal of project-specific or global configurations.

    Key responsibilities include:

    • MCP Server Configuration: Automating the setup of MCP entries.
    • Plugin Runtime: Intercepting events like chat.message, tool.execute.before, and tool.execute.after to allow the pet to react to editor actions.
    • Setup/Removal Management: Managing instruction files and configuration arrays in .opencode/ (project-level) or ~/.config/opencode/ (global-level).
    • Instruction Generation: Creating .opencode/openpets.md files to guide the agent's behavior within the editor.

  7. Understand the OpenPets Desktop Subsystems

    main

    The OpenPets Desktop application is composed of several specialized subsystems that manage the UI, pet lifecycle, and communication:

    • Tray & Windows: Manages the system tray icon, context menus (including update status and logs), and the Control Center (the main management window).
    • Control Center (Renderer): A React/Tailwind-based UI used to manage Dashboard, Pets, Integrations, Plugins, and Settings. It is a pure consumer of data via a preload bridge and has no privileged capabilities.
    • Pet Windows: Handles the actual rendering and motion of pets using specific controllers (default-pet-controller.ts or agent-pet-controller.ts).
    • Local IPC Server: A versioned JSON protocol running over Unix sockets, Windows named pipes, or TCP that allows external clients (like agents) to communicate with the app.
    • Plugin Subsystem: A sandboxed environment for third-party extensions, managing manifests, runtime, and a permission-gated SDK bridge.
    • App State: Persists configuration (installed pets, onboarding, locale, etc.) in a versioned JSON document at userData/openpets-state.json.

  8. Understand the OpenPets Desktop Architecture

    main

    The OpenPets Desktop application is organized into several functional domains that manage the lifecycle of pets, plugins, and user interfaces:

    • Core: Manages the application lifecycle, persistent state (app-state.ts), and structured logging (logger.ts).
    • UI: Handles the system tray, the Control Center (via windows.ts and a React/Tailwind renderer), and pet window rendering.
    • Pets: Manages pet window creation, movement via the pet-motion-engine.ts, and reaction animations.
    • IPC: Facilitates local communication via local-ipc.ts using a net.Server implementation, allowing CLI tools and other processes to interact with pets.
    • Plugins: A robust system supporting both declarative and JavaScript runtimes, managed by a plugin-service.ts and executed within sandboxed environments.
    • Agent Integration: Provides hooks and configuration for AI agents like Claude, OpenCode, and Cursor, including MCP (Model Context Protocol) support.

  9. Understand @open-pets/cursor responsibility and design

    main

    The @open-pets/cursor package is a Node.js utility designed to manage Cursor editor integration files. It specifically handles:

    1. MCP Configuration: Managing OpenPets Model Context Protocol (MCP) entries in Cursor's mcp.json files (both global and project-specific).
    2. Cursor Rules: Managing project-local Cursor rules guidance in .cursor/rules/openpets.mdc.

    Configuration Path Resolution

    • Global config: <homeDir>/.cursor/mcp.json
    • Project config: <projectDir>/.cursor/mcp.json
    • Rules path: <projectDir>/.cursor/rules/openpets.mdc

    Note: All APIs accept an explicit configPath for custom locations.

    Safety Constraints

    • Strict JSON: Only standard JSON is supported (no JSONC comments).
    • Size Limits: Maximum config size is 256 KiB; maximum rules size is 64 KiB.
    • Security: Rejects symlinks at any path level and uses atomic writes with automatic backups and private file permissions (0o600) where supported.

  10. Explore OpenPets Documentation

    main

    The OpenPets documentation is organized into a narrative layer that explains concepts, contracts, and system architecture. It is designed to complement the codemap.md files found throughout the repository, which serve as the authoritative source for every symbol and responsibility.

    To understand the project, start with the architecture.md guide to grasp the runtime topology, package spine, and end-to-end flows.

  11. Explore the OpenPets Directory Structure

    main

    The repository is organized into apps/, packages/, and plugins/:

    apps/ (Deployable Applications)

    • apps/desktop/: The main Electron companion app (Tray UX, pet windows, plugin runtime).
    • apps/desktop/src/renderer/: The React/Tailwind Control Center UI.

    packages/ (Shared NPM Packages)

    • @open-pets/client: IPC client for discovering and communicating with the desktop app.
    • @open-pets/cli: User-facing CLI for pet management and MCP launch.
    • @open-pets/mcp: MCP server for agent tool exposure.
    • @open-pets/sdk: Public SDK v3 type contracts for plugin authors.
    • @open-pets/agent-events: Shared speech/event message pools.
    • @open-pets/cursor / @open-pets/pi / @open-pets/opencode: Specific editor integration packages.
    • @open-pets/pet-format: Marker package for pet identity.
    • @open-pets/install-pet: Standalone installer for catalog pets.

    plugins/ (Plugin Source)

    • plugins/official/: First-party SDK v3 plugins containing manifests, assets, and locales.

  12. Explore OpenPets documentation

    main

    Detailed architecture and platform documentation can be found in the docs/ directory. Key resources include:

    • Plugin Platform: docs/plugins.md contains the SDK v3 specification, permission models, and testing toolkits.
    • Claude Integration: docs/claude-integration.md covers integration with Claude Code, including memory, hooks, and MCP.
    • OpenCode Integration: docs/opencode.md explains integration with OpenCode workspaces.
    • WSL Setup: docs/wsl-ipc.md provides instructions for setting up a TCP bridge from WSL to Windows.
    • Testing: docs/testing.md covers workspace testing and consistency strategies.
    • Release Process: docs/release.md details application packaging and release workflows.
    • Development Workflow: docs/workflow.md outlines core development and contribution workflows.