OpenPets Dev 6ab3bb64d8 feat(rebrand): rename OpenPets to FamiliarOS and pets to familiars

- Rename all user-facing and technical identifiers from OpenPets/Pet to FamiliarOS/Familiar.
- Rename packages from @open-pets/* to @familiaros/*; rename install-pet/pet-format packages.
- Rename plugin IDs and directories from openpets.* to familiaros.*.
- Rename IPC namespace from openpets:* to familiaros:* and state filenames from openpets-* to familiaros-* with legacy migration.
- Rename source files (pet-window, built-in-pet, default-pet-controller, etc.) to familiar equivalents.
- Update locales (en, es-419, ja, ko, pt-BR, zh-Hans, zh-Hant) and tray/pet context menu strings.
- Add Familiar naming feature: preference, settings input, tray menu display.
- Update assets and packaging config; all desktop tests pass.

2026-06-17 01:42:08 +00:00

3.3 KiB

Raw Permalink Blame History

packages/

Monorepo workspace containing all FamiliarOS npm packages. Each package is independently publishable with its own versioning.

Responsibility

Provides modular, reusable components for the FamiliarOS ecosystem:

familiar-format: Package marker interface for type identification
agent-events: Speech pools and validation for agent feedback messages
client: Core IPC client for communicating with FamiliarOS desktop app
cli: Main CLI tool for configuring agents and managing familiars
mcp: MCP server implementation for agent integration
opencode: OpenCode editor integration (plugin, config management)
claude: Claude Code integration (hooks, MCP config)
cursor: Cursor editor integration (MCP config, project rules)
pi: Pi coding-agent extension integration (event hooks, slash commands)
install-familiar: Standalone familiar installer from gallery catalog

Design/Patterns

Workspace Pattern: Uses pnpm workspaces with workspace:* dependencies for internal linking.

Package Structure: Each package follows consistent structure:

src/ - TypeScript source
dist/ - Compiled output (not committed)
package.json - Standard npm metadata with exports map
contracts/ - Runtime contract validation tests (client package)
Contract check files (check-*.ts) for runtime validation (other packages)

ESM-First: All packages are ESM ("type": "module") with dual exports for types.

Versioning: Independent versioning per package (currently 2.1.x for active integrations).

Flow

CLI Entry (packages/cli/src/index.ts)
    ├── Configures Claude → @familiaros/claude
    ├── Configures OpenCode → @familiaros/opencode
    ├── Configures Cursor → @familiaros/cursor
    ├── Spawns MCP server → @familiaros/mcp
    └── Uses IPC client → @familiaros/client

MCP Server (packages/mcp/src/index.ts)
    ├── Registers tools (status, react, say)
    └── Communicates via @familiaros/client

OpenCode Plugin (packages/opencode/src/plugin.ts)
    └── Hooks into editor events → @familiaros/client

Claude Hooks (packages/claude/src/hooks.ts)
    └── Processes hook events → @familiaros/client

Cursor Setup (packages/cursor/src/cursor-project-setup.ts)
    └── Writes MCP config + rules → @familiaros/client

Pi Extension (packages/pi/src/extension.ts)
    └── Registers Pi extension hooks/commands → @familiaros/client

Integration Points

Inter-Package Dependencies:

cli depends on: client, claude, mcp, opencode, cursor
mcp depends on: client
claude depends on: client, agent-events
opencode depends on: client, agent-events
cursor depends on: client
pi depends on: client, agent-events and declares optional @earendil-works/pi-coding-agent peer support
install-familiar depends on: client

External Integrations:

@modelcontextprotocol/sdk - MCP protocol implementation
jsonc-parser - JSON with comments parsing for OpenCode configs
yauzl - ZIP extraction for familiar downloads
zod - Schema validation in MCP tools

Desktop App Communication: All packages ultimately communicate with the FamiliarOS desktop app via the IPC protocol defined in client/src/protocol.ts, supporting Unix sockets, Windows named pipes, and TCP (for WSL cross-platform).

3.3 KiB Raw Permalink Blame History