OpenPets is a pnpm/TypeScript monorepo for an Electron desktop companion app, a standalone VS Code extension foundation, and npm packages that let coding agents control animated desktop pets. The workspace provides a local IPC protocol, MCP server, CLI tooling, and editor/agent integrations for Claude Code, OpenCode, Cursor, Zed, Devin, Pi, and OpenClaw.
package.json: workspace scripts for building, checking, testing, desktop packaging, and npm release orchestration.pnpm-workspace.yaml: workspace membership forapps/*andpackages/*.apps/desktop/src/main.ts: Electron main-process bootstrap for the desktop pet app.apps/vscode-extension/src/extension.ts: VS Code UI-host extension foundation activation and surface registration.packages/cli/src/index.ts: command-line setup, pet management, MCP launch, and plugin scaffold/validation entry point.packages/mcp/src/index.ts: MCP server entry point used by agents.packages/client/src/index.ts: public IPC client API consumed by integrations and tools.packages/cursor/src/index.ts: Cursor MCP/rules setup API.packages/zed/src/index.ts: Zed MCP settings management API.packages/devin/src/index.ts: Devin Desktop + Devin CLI MCP config, hook config, and hook payload mapping API.packages/pi/src/extension.ts: Pi coding-agent extension runtime entry point.packages/openclaw/src/index.ts: Native OpenClaw plugin entry point and lifecycle-management exports.packages/sdk/src/index.ts: public SDK v3 type contract for plugin authors.scripts/capture.mjs:pnpm capturerunner for the long-running dev screenshot session (docs/screenshots.md); scenarios live inscripts/capture-scenarios/.plugins/official/: first-party SDK v3 plugin product source consumed by desktop dev mode and plugin packaging/catalog release workflows.
| Directory | Responsibility Summary | Detailed Map |
|---|---|---|
apps/ |
Application workspace containing the tray-first Electron desktop app and a standalone VS Code extension foundation. | View Map |
apps/desktop/ |
User-facing Electron companion app: tray UX, pet windows, pet installation, host-owned Pet Assistant/local conversation archive, plugin automation/runtime, agent setup including OpenClaw management, update checks, and local IPC server. | View Map |
apps/vscode-extension/ |
Standalone VS Code UI-host companion, catalog and wardrobe base with editor/sidebar webviews; not publicly released. | View Map |
apps/desktop/contracts/ |
Desktop public-boundary contract tests for catalog fixtures, local IPC protocol behavior, and plugin manifest schema validation. | View Map |
apps/desktop/src/ |
Main-process service layer for app lifecycle, state, tray/windows, IPC routing, lease-managed agent pets, catalog installation, SDK v3 plugin subsystem, i18n, and editor integration. | View Map |
apps/desktop/src/i18n/ |
Desktop host i18n catalogs and localized reaction speech pools. | View Map |
apps/desktop/src/i18n/locales/ |
Host UI locale dictionaries keyed by BCP-47 locale. | View Map |
apps/desktop/src/i18n/reactions/ |
Localized pet reaction message pools. | View Map |
apps/desktop/src/renderer/ |
Vite renderer workspace for the sandboxed React/Tailwind Control Center bundle. | View Map |
apps/desktop/src/renderer/src/ |
React/Tailwind Control Center UI for Dashboard, Pets, Integrations, Plugins, and Settings via narrow preload APIs. | View Map |
apps/desktop/scripts/ |
Desktop package cleanup and local release automation scripts. | View Map |
infra/linux-vms/ |
Reproducible VMware/Vagrant Linux desktop test VMs (GNOME, KDE X11, COSMIC), guest provisioning, and the host vm driver; see docs/development.md. |
— |
packages/ |
Publishable npm package workspace for shared protocol, CLI, MCP, and coding-agent integrations. | View Map |
packages/agent-events/ |
Shared agent speech/event message pools and validation utilities. | View Map |
packages/agent-events/src/ |
Source implementation for agent event messages. | View Map |
packages/claude/ |
Claude Code integration package for hooks, MCP setup, and settings/memory management. | View Map |
packages/claude/src/ |
Claude Code hook handlers, hook settings, CLI integration, and exported setup APIs. | View Map |
packages/client/ |
IPC client package that discovers and communicates with the desktop app. | View Map |
packages/client/contracts/ |
Client protocol contract tests for discovery, endpoint validation, responses, and pet result parsing. | View Map |
packages/client/src/ |
Protocol definitions, discovery logic, public client API, and smoke entry points. | View Map |
packages/cli/ |
User-facing OpenPets CLI package. | View Map |
packages/cli/src/ |
CLI command parsing and orchestration across client, Claude, OpenCode, Cursor, Zed, Devin, and MCP packages. | View Map |
packages/cursor/ |
Cursor editor integration package for managed MCP configuration and project-local rules. | View Map |
packages/cursor/src/ |
Cursor config/rules planning, status classification, safe writes, previews, and validation checks. | View Map |
packages/zed/ |
Zed editor integration package for managed global MCP settings. | View Map |
packages/zed/src/ |
Zed JSONC settings path resolution, MCP entry construction, status classification, safe writes, and validation checks. | View Map |
packages/devin/ |
Devin integration package for the user-scope MCP config shared by Devin Desktop and Devin CLI. | View Map |
packages/devin/src/ |
Devin MCP and hook config paths, entry/command construction, status classification, hook payload mapping, JSONC-preserving safe writes, and validation checks. | View Map |
packages/install-pet/ |
Standalone installer package for gallery/catalog pets. | View Map |
packages/install-pet/src/ |
Pet installation command implementation. | View Map |
packages/mcp/ |
MCP server package exposing OpenPets tools to compatible agents. | View Map |
packages/mcp/src/ |
MCP server bootstrap, argument parsing, tool registration, and executable validation helpers. | View Map |
packages/opencode/ |
OpenCode editor integration package with plugin runtime and global setup helpers. | View Map |
packages/opencode/src/ |
OpenCode plugin, config mutation, previews, status, and project/global setup modules. | View Map |
packages/pi/ |
Pi coding-agent integration package with extension runtime and slash command support. | View Map |
packages/pi/src/ |
Pi extension entry point, event classification, OpenPets command parsing, and validation checks. | View Map |
packages/openclaw/ |
Native OpenClaw plugin package with local-only lifecycle reactions and OpenClaw install/status planning. | View Map |
packages/openclaw/src/ |
OpenClaw plugin entry/runtime, management command planning, and package contract checks. | View Map |
packages/pet-format/ |
Shared pet contracts, catalog client, and Node package-validation policy. | View Map |
packages/pet-format/src/ |
Reaction, sprite, animation, metadata, wardrobe, activity, catalog, and Node validation implementations. | View Map |
packages/sdk/ |
Public plugin SDK v3 type package and deterministic test harness. | View Map |
packages/sdk/src/ |
SDK type contract, mock runtime, fake clock, and plugin test harness implementation. | View Map |
plugins/ |
Root product source for first-party SDK v3 OpenPets plugins before catalog packaging and R2 upload. | View Map |
plugins/official/ |
Official reviewed SDK v3 plugins with manifests, entries, assets, locales, and harness tests. | View Map |
- The desktop app starts
apps/desktop/src/main.ts, initializes app state, creates tray/task windows, and starts a local IPC server. - Agent integrations (
packages/claude,packages/opencode,packages/cursor,packages/zed,packages/devin,packages/pi,packages/openclaw, andpackages/mcp) configure agents or emit pet commands through their configuration APIs and, for runtime integrations,@open-pets/client. OpenClaw is a native OpenClaw plugin with strict local-only, payload-free hooks; Zed is configuration-only and runs the configured MCP server; Devin adds lifecycle hooks that runopenpets hook --agent devin. - The client discovers Unix sockets, Windows named pipes, or TCP endpoints for WSL cross-platform access.
- The desktop IPC server routes commands through lease-managed controllers so default and agent pets can coexist safely.
- The plugin service loads approved catalog or local
openpets.plugin.jsonmanifests, persists plugin state/config, schedules declarative timers, and bridges SDK v3 calls through permission-checked host modules for UI, audio, events, storage, AI, OAuth, voice, panels, and pet control. Plugin voice input remains one-shot, live-track-accounted, cancellable, timeout-bounded, and never ambient; the separate realtime conversation foundation is host-private and not exposed through the SDK. - Pet windows render reaction-driven animations, localized speech, host-rendered bubbles/alerts/HUDs, and status reactions using desktop state plus reaction mapping metadata.
- Pet assets are resolved from built-in assets, locally developed Codex pets, or remotely downloaded catalog ZIPs.
- Workspace packages share TypeScript/ESM build conventions and are wired together through pnpm
workspace:*dependencies. - The standalone VS Code UI host provides a bundled pet and outfits, catalog and local ZIP installation, manual outfits, and editor/sidebar webviews without the desktop IPC service. Scene instances, roaming and settings are implemented; the locally packaged extension is for evaluation, not Marketplace release.
- For repository-level orientation, start here, then open the specific folder codemap before editing.
- Contract validation files named
check-*.tsare intentionally excluded from detailed codemap coverage except where they define package contract boundaries. - Build artifacts, dependencies, tests, documentation, and binary assets are excluded from codemap state.
web/is intentionally excluded from this codemap run; plugin source coverage is underplugins/only.- The API-owned plugin marketplace is documented in
docs/marketplace.md:web/studio/studio/marketplace/owns durable releases and artifacts,web/studio/studio/api/marketplace.pyowns HTTP adapters, andapps/desktop/src/plugin-marketplace.tsconsumes its public contracts.