scriptoriumadmin/openpetswithchatandmcp
1
0
Fork 0
Code Issues Pull requests 6 Projects Releases Packages Wiki Activity Actions
openpetswithchatandmcp/codemap.md
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

7.6 KiB
Raw Blame History

Repository Atlas: FamiliarOS 2.0 Workspace

Project Responsibility

FamiliarOS is a pnpm/TypeScript monorepo for an Electron desktop companion app plus npm packages that let coding agents control animated desktop familiars. The workspace provides a local IPC protocol, MCP server, CLI tooling, and editor-specific integrations for Claude Code, OpenCode, Cursor, and Pi.

System Entry Points

  • package.json: workspace scripts for building, checking, testing, desktop packaging, and npm release orchestration.
  • pnpm-workspace.yaml: workspace membership for apps/* and packages/*.
  • apps/desktop/src/main.ts: Electron main-process bootstrap for the desktop familiar app.
  • packages/cli/src/index.ts: command-line setup and familiar management 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/pi/src/extension.ts: Pi coding-agent extension runtime entry point.
  • plugins/official/: first-party plugin product source consumed by desktop dev mode and web catalog sync.

Directory Map

Directory Responsibility Summary Detailed Map
apps/ Deployable application workspace, currently the tray-first Electron desktop app that consumes shared packages, local IPC, familiar windows, and desktop plugin support. View Map
apps/desktop/ User-facing Electron companion app: tray UX, familiar windows, familiar installation, plugin automation/runtime, agent setup, update checks, and local IPC server. 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 familiars, catalog installation, plugin subsystem, and editor integration. 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, Familiars, Integrations, Plugins, and Settings via narrow preload APIs. View Map
apps/desktop/scripts/ Desktop package cleanup and local release automation scripts. View Map
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 familiar result parsing. View Map
packages/client/src/ Protocol definitions, discovery logic, public client API, and smoke entry points. View Map
packages/cli/ User-facing FamiliarOS CLI package. View Map
packages/cli/src/ CLI command parsing and orchestration across client, Claude, OpenCode, 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/install-familiar/ Standalone installer package for gallery/catalog familiars. View Map
packages/install-familiar/src/ Familiar installation command implementation. View Map
packages/mcp/ MCP server package exposing FamiliarOS 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, FamiliarOS command parsing, and validation checks. View Map
packages/familiar-format/ Minimal package marker/type interface for FamiliarOS familiar package identity. View Map
packages/familiar-format/src/ Marker source export for familiar-format package consumers. View Map
plugins/ Root product source for first-party FamiliarOS plugins before web catalog packaging and R2 upload.
plugins/official/ Official plugin manifests and single-file JavaScript entries loaded by desktop dev mode and packaged by web sync.

Architecture Flow

  1. The desktop app starts apps/desktop/src/main.ts, initializes app state, creates tray/task windows, and starts a local IPC server.
  2. Agent integrations (packages/claude, packages/opencode, packages/cursor, packages/pi, and packages/mcp) configure agents or emit familiar commands through @familiaros/client.
  3. The client discovers Unix sockets, Windows named pipes, or TCP endpoints for WSL cross-platform access.
  4. The desktop IPC server routes commands through lease-managed controllers so default and agent familiars can coexist safely.
  5. The plugin service loads approved catalog or local familiaros.plugin.json manifests, persists plugin state/config, schedules declarative timers, and bridges allowed actions into the default familiar API.
  6. Familiar windows render reaction-driven animations, speech bubbles, and status badges using desktop state plus reaction mapping metadata.
  7. Familiar assets are resolved from built-in assets, locally developed Codex familiars, or remotely downloaded catalog ZIPs.
  8. Workspace packages share TypeScript/ESM build conventions and are wired together through pnpm workspace:* dependencies.

Working Notes

  • For repository-level orientation, start here, then open the specific folder codemap before editing.
  • Contract validation files named check-*.ts are intentionally excluded from detailed codemap coverage.
  • Build artifacts, dependencies, tests, documentation, and binary assets are excluded from codemap state.