OpenPets

https://openpets.dev/docs
Admin
OpenPets is a desktop pet app for coding agents and AI assistants. It shows a small animated pet on...
Tokens:47,504
Snippets:675
Trust Score:4.9
Update:4 months ago
Show doc for...
Tokens:
Raw
### Installing Dependencies and Building Workspace

Source: https://openpets.dev/docs/plugins

Standard setup commands for the OpenPets project. Install pnpm and Node.js (v20+), then run these commands to install dependencies and build all workspace packages.

```bash
pnpm install
```

```bash
pnpm build
```

```bash
pnpm dev:desktop
```

--------------------------------

### Start OpenPets MCP Server

Source: https://openpets.dev/docs/plugins

Starts the OpenPets MCP server, which communicates with the desktop app. Use `--pet <id>` to target a specific installed pet.

```bash
openpets mcp [--pet <id>]
```

--------------------------------

### Install @open-pets/client

Source: https://openpets.dev/docs/plugins

Install the core IPC client package. This is used by other OpenPets packages to communicate with the desktop app.

```bash
npm install @open-pets/client
```

--------------------------------

### Install and Configure @open-pets/cli

Source: https://openpets.dev/docs/plugins

Install the OpenPets CLI package for managing installations, configurations, MCP, and hooks. You can use npx for a temporary installation or npm install -g for a global one.

```bash
npx -y @open-pets/cli@latest configure --agent claude
# optional permanent shell command:
npm install -g @open-pets/cli
```

--------------------------------

### Client Config Example - Generic stdio MCP

Source: https://openpets.dev/docs

Example JSON configuration for generic stdio MCP clients like Cursor and Windsurf.

```APIDOC
### Cursor, Windsurf, generic stdio MCP Configuration

mcp.json
```json
{
  "mcpServers": {
    "openpets": {
      "command": "npx",
      "args": ["-y", "@open-pets/mcp"]
    }
  }
}
```

### Description
This configuration is suitable for generic stdio MCP clients. It sets up the OpenPets MCP server using `npx`. If you need to target a specific pet, you can add the `--pet <pet-id>` argument within the `args` array.
```

--------------------------------

### Plugin Package Layout Example

Source: https://openpets.dev/docs/plugin-sdk

This text-based example shows the expected directory structure for a plugin package. It includes the metadata file, spritesheet, and an optional preview image.

```text
<pet-id>/
├── pet.json
├── spritesheet.webp
└── preview.webp    # optional, used as a thumbnail
```

--------------------------------

### Client Config Example - Bundled App Path

Source: https://openpets.dev/docs

Example JSON configuration for using the OpenPets MCP server bundled within the desktop application.

```APIDOC
### Bundled-app path Configuration

mcp.json (bundled)
```json
{
  "mcpServers": {
    "openpets": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/Applications/OpenPets.app/Contents/Resources/app.asar.unpacked/node_modules/@open-pets/mcp/dist/index.js"
      ]
    }
  }
}
```

### Description
This configuration allows you to directly run the MCP server that is shipped with the OpenPets desktop app, bypassing `npx`. This is useful if you want to ensure you are using the locally installed version.
```

--------------------------------

### Install Pet using Standalone Installer

Source: https://openpets.dev/docs/plugins

This command installs a pet without requiring the OpenPets desktop app to be running, suitable for CI or automated environments. It handles direct downloads and validation.

```bash
npx -y install-pet <pet-id>
```

--------------------------------

### Plugin Development Setup and Commands

Source: https://openpets.dev/docs/plugins

These commands are used for local development and testing of plugins. They ensure plugins meet contract requirements and can be packaged correctly.

```bash
pnpm plugins:test
```

```bash
pnpm plugins:check
```

```bash
pnpm plugins:package
```

--------------------------------

### Install a Pet using OpenPets CLI

Source: https://openpets.dev/docs/plugins

Installs a pet from the OpenPets catalog by sending a request to the running desktop app. The pet ID must conform to specific regex rules and the desktop app must be running.

```bash
openpets install <pet-id>
```

--------------------------------

### Verify OpenPets Integration with Assistant

Source: https://openpets.dev/docs/plugins

After installing an integration, restart your assistant and use this prompt to check if OpenPets is available and which pet is configured. This helps confirm the setup is successful.

```text
Can you call openpets_status and tell me which pet I have configured?
```

--------------------------------

### Plugin Manifest Example

Source: https://openpets.dev/docs/plugins

This is an example of an openpets.plugin.json manifest file. It declares plugin metadata, version, entry point, permissions, and configuration schema.

```json
{
  "manifestVersion": 2,
  "id": "your-name.hello-pet",
  "name": "Hello Pet",
  "version": "1.0.0",
  "description": "Greets you when it starts and adds a hello command.",
  "author": "Your Name",
  "runtime": "javascript",
  "entry": "index.js",
  "sdkVersion": "1.0.0",
  "permissions": ["pet:speak", "pet:reaction", "commands", "status"],
  "configSchema": {}
}
```

--------------------------------

### Install Pet from CLI

Source: https://openpets.dev/docs/plugins

Use this command to install a pet using the OpenPets CLI when the desktop app is running. The CLI relays the request to the app for download and validation.

```bash
npx -y @open-pets/cli@latest install <pet-id>
```

--------------------------------

### Client Config Example - Claude Code

Source: https://openpets.dev/docs

Example JSON configuration for setting up the OpenPets MCP server within Claude Code.

```APIDOC
### Claude Code MCP Configuration

~/.claude/mcp.json (excerpt)
```json
{
  "mcpServers": {
    "openpets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@open-pets/mcp", "--pet", "<pet-id>"]
    }
  }
}
```

### Description
This configuration snippet shows how to define the OpenPets MCP server for Claude Code. Replace `<pet-id>` with the desired pet's ID or omit the `--pet` argument to use the default pet.
```

--------------------------------

### Quick Install for Claude Code

Source: https://openpets.dev/docs

This command installs the OpenPets MCP server for Claude Code, allowing it to manage pets.

```APIDOC
## Claude MCP (user scope)

### Command
bash
```
claude mcp add --scope user openpets -- npx -y @open-pets/mcp@latest [--pet <pet-id>]
```

### Description
This command adds the OpenPets MCP server to your user scope for Claude Code. You can optionally specify a particular pet to target using the `--pet <pet-id>` flag.
```

--------------------------------

### Installing Plugin SDK Types

Source: https://openpets.dev/docs/plugins

Install the types-only dev package to enable autocomplete and type-checking for the OpenPets plugin SDK in your editor.

```bash
npm i -D @open-pets/plugin-sdk
```

--------------------------------

### Quick Install with Claude Code

Source: https://openpets.dev/docs/plugins

Use this command to add OpenPets to your client via Claude Code. It handles managed instructions and writes the correct command for your install method.

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

--------------------------------

### Make Linux AppImage Executable and Run

Source: https://openpets.dev/docs/plugins

Commands to make the OpenPets AppImage executable and then run it. This is for Linux distributions where no system installation is required.

```bash
chmod +x OpenPets-*.AppImage
./OpenPets-*.AppImage
```

--------------------------------

### Install OpenPets MCP Server using npm

Source: https://openpets.dev/docs/plugins

This command installs the OpenPets MCP server as a published npm package. You can optionally target a specific pet using the --pet flag.

```bash
npx -y @open-pets/mcp@latest [--pet <pet-id>]
```

--------------------------------

### Pet Package Layout Structure

Source: https://openpets.dev/docs/developer

This text-based example illustrates the expected directory structure for a pet package. It includes the metadata file and optional preview image.

```text
<pet-id>/
├── pet.json
├── spritesheet.webp
└── preview.webp    # optional, used as a thumbnail

```

--------------------------------

### Registering a Plugin Entry Point

Source: https://openpets.dev/docs/plugins

This snippet shows how to register a plugin's start and stop functions using the OpenPetsPlugin API. Ensure the plugin entry file is correctly configured in the manifest.

```javascript
OpenPetsPlugin.register({
  async start(ctx) {
    await ctx.pet.say('Plugin started')
  },
  async stop(ctx) {
    await ctx.pet.react('idle')
  },
})
```

--------------------------------

### Bundled App Path Client Configuration

Source: https://openpets.dev/docs/plugins

Configure your client to use the MCP server that ships inside an installed OpenPets desktop app, skipping the need for npx. This example uses a typical macOS path.

```json
{
  "mcpServers": {
    "openpets": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/Applications/OpenPets.app/Contents/Resources/app.asar.unpacked/node_modules/@open-pets/mcp/dist/index.js"
      ]
    }
  }
}
```

--------------------------------

### Configure Project for AI Assistant

Source: https://openpets.dev/docs/plugins

Sets up an AI assistant for a specific project by writing project-local configuration. This ensures the setup is version-controlled with the repository. Supports specifying the agent, pet, working directory, and other options.

```bash
openpets configure [--agent claude|opencode] [--pet <id>] [--cwd <path>]
                  [--yes] [--force] [--local-dev]
```

--------------------------------

### Run Local Development Plugins

Source: https://openpets.dev/docs/plugins

Load official plugins for dogfooding from the repository root.

```bash
pnpm dev:desktop:plugins
```

--------------------------------

### Running Desktop App with Local Plugins

Source: https://openpets.dev/docs/developer

Configure the desktop app to load local plugins by setting environment variables before launching. Use OPENPETS_DEV_PLUGIN_ROOTS for directories or OPENPETS_DEV_PLUGIN_PATHS for specific manifest files.

```bash
OPENPETS_DEV_PLUGIN_ROOTS=/path/to/plugin-root pnpm dev:desktop:plugins
OPENPETS_DEV_PLUGIN_PATHS=/path/to/openpets.plugin.json pnpm dev:desktop:plugins

```

--------------------------------

### Running Desktop App with Local Plugins

Source: https://openpets.dev/docs

Commands to run the desktop app with local plugin development support, specifying plugin roots or paths.

```bash
OPENPETS_DEV_PLUGIN_ROOTS=/path/to/plugin-root pnpm dev:desktop:plugins

```

```bash
OPENPETS_DEV_PLUGIN_PATHS=/path/to/openpets.plugin.json pnpm dev:desktop:plugins

```

--------------------------------

### Running Desktop App with Local Plugins

Source: https://openpets.dev/docs/plugins

Use these environment variables to point the desktop app to local plugin directories or manifest files for development. This allows for rapid iteration on plugin code.

```bash
OPENPETS_DEV_PLUGIN_ROOTS=/path/to/plugin-root pnpm dev:desktop:plugins
```

```bash
OPENPETS_DEV_PLUGIN_PATHS=/path/to/openpets.plugin.json pnpm dev:desktop:plugins
```

--------------------------------

### Running OpenPets with Local Plugins

Source: https://openpets.dev/docs/plugins

Use this command to launch the OpenPets desktop app with local plugin support enabled, pointing to your plugin development directory.

```bash
OPENPETS_DEV_PLUGIN_PATHS=~/openpets-plugins/hello-pet pnpm dev:desktop:plugins
```

--------------------------------

### Get Current Configuration

Source: https://openpets.dev/docs/plugins

Retrieves the current configuration values for the plugin. This method is always available.

```typescript
config.get<T>(): Promise<T>
```

--------------------------------

### Get Data from Storage

Source: https://openpets.dev/docs/plugins

Retrieves data associated with a specific key from the plugin's persistent storage. Requires the 'storage' permission.

```typescript
storage.get<T>(key: string): Promise<T | undefined>
```

--------------------------------

### Fetch Data via HTTP

Source: https://openpets.dev/docs/plugins

Make GET requests to approved HTTPS endpoints through the OpenPets proxy. Handles URL fetching with options for headers and timeouts.

```typescript
http.fetch(url: string, options?: {
  method?: "GET"
  headers?: Record<string, string>
  timeoutMs?: number
}): Promise<{ 
  status: number
  ok: boolean
  headers: Record<string, string>
  text: string
  json?: unknown
}>
```
Tokens:
Raw