openpetswithchatandmcp/FEATURES.md

# OpenPets Feature Inventory

This file is the current feature roll-up for this working fork of OpenPets.
It combines:

- the shipped baseline described in `README.md`
- the chat, memory, and prompt-window work from this implementation thread
- the curated MCP toolkit surface added in the desktop app

> Looking for an isolated view of only our additions? See:
> - [`FEATURES_OUR_CHANGES.md`](FEATURES_OUR_CHANGES.md)
> - [`README_OUR_CHANGES.md`](README_OUR_CHANGES.md)
> - [`PULL_REQUEST.md`](PULL_REQUEST.md)

## Desktop Companion Core

- Tray-first desktop companion app
- Desktop pet that can idle, react, wave, move, and speak
- Default pet plus installed non-default pets
- Per-agent pet routing when integrations request a specific installed pet
- Manual pet dismissal with lease-aware recovery rules
- Native right-click pet context menu
- Always-on-top pet window with click-through background behavior
- Drag support with mouse passthrough recovery for Windows/Linux edge cases
- Adaptive pet scale setting (continuous slider from 0.16x to 10x in Settings)
- Reset default pet position
- Launch at login support where the platform allows it
- Update checking against GitHub releases
- Open logs folder from the app

## Pet Packs And Gallery

- Built-in default pet
- Installed pet pack loading
- Local pet import from ZIP
- Local pet import from folder
- Codex pet import flow
- Pet catalog browsing
- Pet preview thumbnails and spritesheets
- Default pet selection
- Pet gallery linkout

## Reactions And Speech

- Explicit pet speech bubbles
- Reaction-only decorative bubble messages
- Reaction animation mapping
- User-configurable reaction-to-animation overrides
- Longer display duration for longer messages
- Separate handling for finite reaction animations vs visible bubble lifetime
- Safer speech rules for agent-driven bubble content
- Bubble behavior that avoids showing code, logs, URLs, paths, or secrets in normal integration speech

## Virtual Pet Care

- Bundled `openpets.virtual-pet` plugin tracks hunger, energy, happiness, and affection
- Stats decay slowly while the app is running and recover when you feed, play, pet, or nap
- Status HUD appears only when summoned, so it never blocks the pet or chat
- Triple-click the pet to show the status HUD for 6 seconds
- Actions (feed, play, pet, nap) briefly display the HUD after updating stats
- Automatic nudges when a stat gets low

## Floating Chat Surface

- Double-click the pet to open a floating prompt window
- Floating prompt window stays always on top
- Compact prompt-first mode at 96px height; expanded editor/history mode at 280px
- Prompt bar is sized for 2–3 lines of text
- Resizable corner grip with size remembered per mode
- Prompt window keeps a low desktop footprint
- Minimal top-bar controls with small symbol buttons
- Editor panel toggle
- History toggle
- New chat action
- Settings shortcut
- Close action
- Copy chat support
- Styled conversation history list with per-entry role badges and timestamps
- Scrollable message entries with distinct user/assistant/system/error theming
- Enter sends
- Ctrl+Enter or Cmd+Enter inserts newline
- Inline error presentation inside the prompt surface
- No terminal required for normal chat usage

## Chat History

- Full conversation history stored and persisted to disk across app restarts
- History survives closing and reopening the floating chat window
- History stays in the prompt/editor surface rather than in the pet bubble
- Pet bubble only shows one assistant reply at a time
- Per-entry styling with role badges (You / Pet / System / Error) and timestamps
- **Multi-conversation support**: each conversation is a separate thread with its own messages
- **Conversation list** accessible from the History button in the floating chat window
- **Editor button** shows the current conversation's message list
- Create, switch, and delete conversations from the floating chat window
- Auto-generated conversation titles from the first user message
- Old conversations are preserved when starting a new chat

## OpenAPI And BYOK Chat

- Main-process OpenAPI chat service
- User-entered prompt stays out of the pet renderer
- User-entered prompt stays out of logs unless logging is genuinely necessary elsewhere
- API key or token entry in Settings
- Secure storage with Electron `safeStorage` when available
- Plain local fallback when platform encryption is unavailable
- Model selection in Settings
- OpenAPI-compatible endpoint override in Settings
- Built-in OpenAI endpoint default
- BYOK endpoint support for other compatible providers or local gateways
- Endpoint normalization and validation
- Localhost-only allowance for plain `http`
- Automatic `responses` plus `chat/completions` route selection for broader provider compatibility
- Preset-based provider setup
- Compact single credential entry surface that adapts to the selected provider preset

## Current Provider Presets

- OpenAI
- OpenRouter
- Azure template
- LiteLLM local
- vLLM local
- Custom local template
- Generic HTTPS template

## Pet Character And Personality

- System-prompt style pet character field in General Settings
- Character prompt persists in app state
- Character prompt is applied on future assistant replies
- Base instructions toggle — optionally include or exclude the default OpenPets behavior instructions in every chat
- Theme setting shared between control center and floating chat window
- Auto theme mode
- Light theme mode
- Dark theme mode
- Dark theme tuned toward graphite-style surfaces instead of blue-heavy dark UI

## Memory System

- Local-first persistent OpenPets memory store
- Main-process memory writer
- In-memory retrieval during chat
- On-disk persistence for durable memories
- Human-inspectable memory mirror files
- Relevance-based retrieval into future prompts
- Explicit memory capture patterns such as `remember ...`
- Preference, identity, fact, and note style memory kinds
- Importance weighting
- Tags
- Forget/delete support
- In-app memory viewer in Settings with search, edit, and delete
- **Chat history memory**: cross-conversation message search injects relevant past conversation excerpts into the system prompt
- Two separate databases: explicit memories (`openpets-memory.json`) and chat history (`openpets-chat-history.json`)

## OpenPets MCP Server

- Local IPC discovery file and per-run token flow
- MCP server for OpenPets desktop control
- Explicit target-pet lease routing
- Default-pet fallback when a requested pet is unavailable
- `openpets_status`
- `openpets_react`
- `openpets_say`
- `openpets_memory_list`
- `openpets_memory_search`
- `openpets_memory_store`
- `openpets_memory_forget`

## Agent Integrations

- Claude Code integration
- OpenCode integration
- Cursor integration
- Pi extension guidance
- Global setup preview/state for Claude
- Global setup preview/state for OpenCode
- Global setup preview/state for Cursor
- Managed Claude memory instructions
- Managed Claude hook install/uninstall
- OpenCode instruction file support
- OpenCode plugin support
- Cursor MCP config preview
- Cursor rules preview
- Pet routing per supported integration
- Published package / bundled / local command modes for supported integrations
- Command path overrides for relevant integrations

## Vanilla Chat MCP Tools

- Multi-select MCP tool activation inside the floating chat window
- Tiered tool browser (Starter, Terminal & Systems, Advanced)
- Save & Activate / Deactivate All controls
- Tools run through an internal stdio MCP client in the main process
- Supported tools: filesystem, terminal, memory, fetch-web, sequential-thinking, playwright, git, github, docker, sqlite

## Curated MCP Toolkit Surface

The control-center Integrations page now also includes a curated **MCP Toolkit** panel. This does not pretend to be a full unsafe one-click installer for the whole MCP ecosystem. Instead, it provides a practical, permission-aware reference surface with copyable snippets and docs links.

### Starter Stack In The Toolkit

- Filesystem
- Git
- GitHub
- Playwright
- Browser Use
- SQLite / PostgreSQL guidance
- Memory
- Fetch / Web
- Sequential Thinking
- Docker MCP Toolkit

### Terminal And Systems Layer In The Toolkit

- Shell / Terminal guidance
- Process & Logs guidance
- System Info guidance
- SSH guidance
- Package Manager guidance
- Tmux guidance

### Later / Advanced Layer In The Toolkit

- Kubernetes / Cloud guidance
- CI / CD guidance
- Ghidra guidance
- Binary Analysis guidance
- Network Analysis guidance

### Toolkit UX

- Toolkit card in Integrations
- Explicit `Manual Setup` vs `Persistent Full Access` choice
- Command source labels clarify where tools come from (Stable release, Shipped with app, Local build)
- Install choice descriptions clarify manual vs persistent access
- Tiered MCP family browser
- Per-tool rationale
- Per-tool VectorShell-fit notes
- Per-tool permission-boundary notes
- Copyable install/config snippets where they are stable enough to recommend
- External docs opening through Electron
- Persistent host install bundles for supported hosts
- `Install Now` actions for supported Claude Code and Codex CLI baselines
- Installed/skipped MCP result reporting inside the toolkit UI
- Current automatic baseline: Filesystem, Playwright, Memory, Context7 / Docs, Sequential Thinking, plus Fetch / Web and Browser Use when `uvx` is available

## Plugins

- Plugin catalog
- Installed plugin inspection
- Enable/disable plugins
- Local plugin loading
- Catalog plugin install/update/remove
- Plugin configuration schema rendering
- Plugin command execution
- Plugin status display

## Dashboard And Control Center

- Dashboard overview
- Pet count
- Plugin health summary
- Update status summary
- Reaction mix charting
- Top companion activity
- Activity counters
- Settings view
- Pets view
- Plugins view
- Integrations view
- Persistent route handling inside the control center window

## Logging And Diagnostics

- App log file
- Previous log rollover
- Redaction of token-like values
- Verbose dev logging toggle through environment
- IPC request logging
- Lease acquisition logging
- Pet show lifecycle logging
- Renderer console logging capture

## Packaging And Distribution

- Desktop packaging through Electron Builder
- Windows packaging support
- Linux AppImage packaging support
- Additional Linux targets in config
- Packaged preload scripts for control center, pet window, prompt window, and plugin surfaces
- Packaged official plugins as extra resources
- Packaging contract checks

## Safety And Boundary Rules

- Prompt text is kept out of the pet renderer
- Automatic agent speech is decorative and best effort
- OpenPets speech bubbles are not meant to carry code, logs, URLs, file paths, or secrets
- Tooling guidance in the MCP Toolkit emphasizes minimal permissions
- Docker MCP Toolkit is recommended as an isolation layer when the third-party MCP ecosystem feels too uneven

## Practical Summary

This fork now gives you three layers at once:

- a playful desktop pet
- a floating always-on-top chat surface with BYOK and memory
- a curated MCP/workbench surface for building a serious developer stack around the pet instead of only driving it from a terminal