Pets

Appearance

Frequently Asked Questions ​

General ​

What is OpenPets? ​

OpenPets is a friendly ecosystem of AI "pets" (plugins) that integrate with AI-powered development tools. Each pet provides tools to interact with external services.

How is OpenPets different from MCP? ​

OpenPets builds on top of the Model Context Protocol (MCP) but provides:

  • A friendlier, pet-themed developer experience
  • A full-featured CLI (pets command)
  • A desktop application for visual management
  • Simplified plugin creation with factory patterns
  • Built-in testing and validation

Is OpenPets free? ​

Yes, OpenPets is open source under the MIT license.

Installation ​

How do I install OpenPets? ​

bash
curl -fsSL https://pets.raggle.co/install | bash

Or via npm/bun:

bash
npm install -g openpets
# or
bun add -g openpets

Where are pets installed? ​

Pets are cached in the OpenPets package cache.

Where are pets deployed? ​

For pets maintained in this repository, the primary deployment location is the OpenPets hosted source registry:

  • Manifest: https://pets.raggle.co/source-pets/source-manifest.json
  • Tarballs: https://pets.raggle.co/source-pets/<pet-name>-<version>.tgz

npm publication is optional/secondary. A pet can be available to pets search, pets info, and pets add even if npm view @openpets/<pet-name> returns 404.

Do pets add, pets prune, and pets info use local workspace pets? ​

No. For bare pet names, these commands resolve remote packages from the OpenPets source registry first. npm fallback is only used when explicitly enabled or when a command is specifically doing npm publishing/release work. They do not inspect local directories like pets/<name>.

If a package is not found, the CLI may suggest similar known pet IDs from the remote or bundled registry index. For local development, use an explicit local path with commands that support local plugin execution, such as pets exec <tool> --plugin ./pets/<name>/index.ts.

How do I update a pet? ​

bash
# Remove from cache and reinstall
./scripts/refresh-install.sh pet-name
pets add pet-name

Configuration ​

My pet won't connect. What should I check? ​

  1. Verify environment variables are set: cat .env
  2. Run validation: pets validate
  3. Test connection: bun test:pet pet-name --query "test connection"

Where do I put my API keys? ​

Create a .env file in your project root:

bash
JIRA_API_KEY=your_key_here
JIRA_BASE_URL=https://your-domain.atlassian.net

Can I use multiple pets at once? ​

Yes. Use pets add <pet-name> for each package you want available, or point local test commands at explicit pet paths during development.

Development ​

How do I create a new pet? ​

bash
cd pets/
cp -r _TEMPLATE_ my-new-pet
cd my-new-pet
# Edit index.ts and package.json

See the Development Guide for detailed instructions.

Why can't I use nested objects in schemas? ​

OpenPets runtime schemas intentionally stay flat for compatibility across AI clients. Use JSON string serialization for complex data:

typescript
schema: z.object({
  dataJson: z.string().describe("JSON string of complex data")
})

How do I test my pet locally? ​

bash
cd pets/my-pet
pets validate
bun test:pet my-pet --query "test connection"

How do I publish my pet? ​

For repo pets, merge the pet source and verify the hosted source registry:

bash
pets info pet-name
pets search pet-name

pets info should say it read from a source registry tarball.

npm publishing is secondary and only needed for an explicit npm release:

bash
pets publish --preview  # Dry run first
pets publish            # Publish to npm when intended

Troubleshooting ​

"Pet not found" error ​

  1. Check if the pet is installed: pets list
  2. Try reinstalling: pets add pet-name

"API key not configured" error ​

  1. Check your .env file exists
  2. Verify the variable name matches what the pet expects
  3. Run pets validate to see configuration status

Desktop app won't launch ​

bash
# Kill any existing processes
lsof -ti:1420 | xargs kill -9
# Relaunch
pets

Getting Help ​