openpetswithchatandmcp/apps/desktop/codemap.md

apps/desktop/

Responsibility

FamiliarOS desktop companion application. Tray-first Electron app providing animated desktop familiars that react to coding agent events. Manages familiar installations, the React/Tailwind Control Center, plugin automation/runtime, agent integrations (Claude Code, OpenCode, Cursor, Pi guidance), and local IPC for CLI communication.

Design

• Tray-First UX: No default main window; tray actions open the singleton React/Tailwind Control Center and route directly to Dashboard, Familiars, Integrations, Plugins, and Settings.
• Single Instance: Uses app.requestSingleInstanceLock() with second-instance focusing
• Security Model:
  • Sandboxed renderers with contextIsolation
  • Preload scripts expose limited APIs via contextBridge
  • CSP: default-src 'none', inline styles only
  • Mock keychain to prevent OS credential prompts
  • IPC network security: loopback/private address filtering for TCP mode
• State Management: File-based JSON state with atomic writes (temp + rename)
• Familiar Architecture:
  • Default familiar (always visible when enabled)
  • Agent familiars (lease-based, appear on explicit agent requests)
  • Built-in fallback familiar (bundled spritesheet)
  • Speech bubbles with reaction messages and status badges
  • User-configurable reaction-to-animation mapping
• Lease Manager: 15s TTL leases for agent familiar routing with heartbeat renewal
• Logging: Structured logging with scopes, log rotation (2MB max), and sensitive data redaction
• Plugin Subsystem: Declarative manifest plugins and JavaScript plugin hosting with permission approval, config schemas, command/status surfaces, catalog/local installs, SDK bridge quotas, storage, schedules, restricted HTTPS fetch, and safe path/ZIP/manifest validation

Flow

Startup: main.ts → installAppLifecycle() → initializeAppState() → initializeLogger() → createAppTray() → startLocalIpcServer() → initialize plugin service with JavaScript host/SDK bridge → optionally showDefaultPet()

Familiar Display: IPC Request → local-ipc.ts → LeaseManager.acquire() → agent-familiar-controller.ts → familiar-window.ts → HTML/CSS spritesheet animation with reaction-to-animation mapping

Installation: Catalog fetch (V3 with pagination fallback to V2) → ZIP download → yauzl extraction → validation → state update → tray refresh

Agent Setup: UI → agent-setup.ts → Claude/OpenCode/Cursor CLI detection → MCP config modification → hooks installation → memory file management

Control Center: Tray route → openControlCenterWindow(route) → windows.ts loads Vite renderer and sends route events → control-center-preload.cjs exposes narrow page APIs → React Dashboard/Familiars/Integrations/Plugins/Settings routes render snapshots and invoke actions.

Plugins: Control Center plugins route → plugin-service.ts → catalog or local manifest/entry loader → permission approval/state update → plugin-runtime.ts schedules declarative timers or starts plugin-js-host.ts → plugin-sdk-bridge.ts applies approved SDK calls to familiar/schedule/storage/command/status/network APIs

Integration Points

• Workspace Packages: @familiaros/agent-events, @familiaros/claude, @familiaros/cli, @familiaros/cursor, @familiaros/mcp, @familiaros/opencode
• External Services:
  • https://familiaros.dev/familiars/catalog.v2.json (familiar catalog V2)
  • https://familiaros.dev/familiars/catalog.v3.json (familiar catalog V3 with pagination)
  • https://familiaros.dev/plugins/catalog.v1.json (plugin catalog V1)
  • https://zip.familiaros.dev/familiars/{id}.zip (familiar downloads)
  • https://zip.familiaros.dev/plugins/{id}.zip (plugin downloads)
  • GitHub API (release checks)
• System Integration:
  • Claude Code: ~/.claude/CLAUDE.md, ~/.claude/settings.json, claude mcp commands
  • OpenCode: ~/.opencode/config.json
  • Cursor: ~/.cursor/mcp.json, .cursor/rules/familiaros.mdc
  • Codex: ~/.codex/familiars/ (local familiar development)
  • IPC: Discovery file at platform-specific path, Unix socket/Windows named pipe/TCP
  • Logs: userData/logs/familiaros.log
• Build: electron-builder with ASAR, cross-platform (macOS/Windows/Linux)

Key Files

• main.ts: Entry point, lifecycle coordination
• tray.ts: System tray icon and menu
• windows.ts: Control Center BrowserWindow management, Dashboard snapshot, route targeting, IPC handlers, and internal protocols
• renderer/: React/Tailwind Control Center for Dashboard, Familiars, Integrations, Plugins, and Settings
• local-ipc.ts: TCP/Unix socket server for CLI communication
• lease-manager.ts: Familiar routing lease lifecycle
• familiar-window.ts: Familiar rendering (transparent frameless windows, CSS sprite animation, speech bubbles, status badges)
• default-familiar-controller.ts/agent-familiar-controller.ts: Familiar visibility/state management with transient displays
• app-state.ts: Persistent state management (JSON file)
• agent-setup.ts: Claude/OpenCode/Cursor integration logic
• plugin-service.ts: Plugin orchestration for snapshots, enable/config/reload, command execution, catalog install/update/uninstall, local loading, permission approval, JavaScript host wiring, and runtime reloads
• plugin-manifest.ts: familiaros.plugin.json v1/v2 schema/types/validator for declarative timer plugins and JavaScript SDK plugins, config fields, permissions, commands/status/network, and actions
• plugin-runtime.ts: Runtime that compiles enabled declarative timers and starts JavaScript plugin hosts for approved familiar/schedule/storage/command/status/network actions
• plugin-state.ts: Atomic JSON state store for installed plugins, enabled flag, approved permissions, config, broken state, and update metadata
• plugin-config.ts: Plugin default/effective config validation and config reference resolution
• plugin-catalog.ts/plugin-catalog-validation.ts: Plugin catalog fetch/cache and strict catalog entry validation
• plugin-package.ts: Catalog plugin ZIP download, SHA-256 verification, manifest extraction, install, and safe uninstall path resolution
• plugin-local-loader.ts: Local developer plugin folder validation and manifest snapshotting into app data
• plugin-manifest-reader.ts: Safe installed-manifest reader enforcing allowed roots, size limits, path containment, and expected id/version
• plugin-familiar-api.ts: Runtime bridge from plugin actions to default familiar speech/reaction APIs
• plugin-js-host.ts: Hidden sandboxed BrowserWindow host for JavaScript plugin entry modules, SDK IPC tokening, session hardening, startup handshake, and teardown
• plugin-sdk-bridge.ts: Permission-checked SDK API for JavaScript plugins with quotas, plugin storage, schedules, config listeners, commands/status, logs, and restricted HTTPS fetch
• familiar-installation.ts: Catalog ZIP download and extraction
• codex-familiars.ts: Local Codex familiar import
• catalog.ts: Remote catalog fetching with V3 pagination and fixture fallback
• logger.ts: Structured logging with scopes (app, ipc, lease, familiar, state, tray, ui)
• reaction-animation-mapping.ts: Reaction-to-animation state mapping with user overrides
• reaction-messages.ts: Message pools for each reaction type
• control-center-preload.cjs/familiar-preload.cjs/plugin-sdk-preload.cjs: Narrow contextBridge APIs for the Control Center, familiar windows, and plugin SDK host; the legacy preload.cjs task-window bridge and plugins-window.ts UI have been removed
• electron-builder.yml: Packaging configuration
• scripts/release-local.mjs: macOS-local release automation with GitHub draft creation
• contracts/catalog-fixture.contract.ts: Catalog V2 validation contract tests against fixture data
• contracts/local-ipc-protocol.contract.ts: IPC protocol validation contract tests for request/response parsing
• contracts/plugin-manifest.contract.ts: Plugin manifest boundary contract for v1 schema, config references, permissions, deferred features, and action validation

Test Structure

• Behavior tests (tests/*.test.ts): Unit tests for lease manager, state management, version checking, ZIP safety, Codex familiars, Claude memory, and reaction animation mapping. Compiled to .test-dist/tests/.
• Contract tests (contracts/*.contract.ts): Public API boundary validation for catalog fixtures, IPC protocol, and plugin manifest schema. Compiled to .test-dist/contracts/.
• Runtime checks (src/check-*.ts): Remaining runtime validation checks compiled to dist/.
• Test runner (scripts/run-tests.mjs): Orchestrates preload syntax checks → test compilation → behavior tests → contract tests → dist checks.