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 Blame History

packages/claude/

Claude Code integration for FamiliarOS.

Responsibility

Provides Claude Code editor integration via MCP configuration and lifecycle hooks. Manages hook installation, event handling, and speech feedback during Claude Code sessions.

Design

CLI Entry (cli.ts):

Commands: hook, doctor-hooks, install-hooks, uninstall-hooks
--settings path override, --familiar targeting, --project-local flag
Delegates to hooks.ts and hook-settings.ts

Hook Execution (hooks.ts):

runClaudeHookFromStdin() - Main entry for Claude hook protocol
Event mapping: UserPromptSubmit → thinking, PermissionRequest → waiting, Stop → success, StopFailure → error, PreToolUse → tool-specific
Tool classification: Edit/Write/MultiEdit → "editing", Bash with test commands → "testing"
Project-local detection: Checks .claude/settings.local.json for --familiaros-managed --project-local
Throttling: 20s speech, 3s permission, 10s reaction cooldowns via JSON state file
Lease acquisition for targeted familiars
Error handling: Debug logging, graceful degradation

Hook Settings Management (hook-settings.ts):

Settings path: ~/.claude/settings.json
Hook events: UserPromptSubmit, PreToolUse, PermissionRequest, Notification, Stop, StopFailure
Command entry: { type: "command", command, timeout: 3, async: true, asyncRewake: false }
Marker: --familiaros-managed in command for identification
Install modes: published (npx), local (node path), bundled (asar unpacked)
Safety: Backup before write, atomic rename, permission checks
Status: not_installed, installed, needs_update, error

MCP Configuration (claude-code.ts):

MCP server name: familiaros
Command modes: published (npx -y @familiaros/mcp), local/bundled (node path)
Claude CLI integration: claude mcp add, claude mcp get, claude mcp remove
Output parsing: Handles both JSON and text formats from claude mcp get
Path safety: Validates local/bundled paths are within expected directories
Asar handling: mapAsarPathToUnpacked() for Electron apps

Speech Messages (hook-messages.ts):

Re-exports from @familiaros/agent-events

Flow

Claude Hook Event (stdin JSON)
    ↓
runClaudeHookFromStdin() → readLimitedStdin()
    ↓
parseHookPayload() → mapClaudeHookEvent()
    ↓
Decision: { reaction?, speechCategory? }
    ↓
hasProjectLocalFamiliarOSHook() → Skip if project-local exists
    ↓
shouldSendSpeech() / shouldSendReaction() → Throttle check
    ↓
acquireHookLease() → Get leaseId for targeted familiar
    ↓
client.say(message, { reaction, leaseId }) or client.react(reaction, { leaseId })

Integration Points

Dependencies:

@familiaros/client - IPC communication
@familiaros/agent-events - Speech pools

External Commands:

claude - Claude Code CLI for MCP and settings management

Consumers:

@familiaros/cli - configure command for Claude projects

Exports:

claudePackageName constant
runClaudeHookFromStdin(), handleClaudeHookPayload()
installClaudeHooks(), uninstallClaudeHooks(), doctorClaudeHooks()
buildClaudeMcpPreview(), parseClaudeMcpGetOutput(), classifyClaudeMcpStatus()
validateFamiliarOSPetArg(), openPetsHookMarker, claudeHookEvents

3.3 KiB Raw Blame History