openpetswithchatandmcp/packages/cli/codemap.md

packages/cli/

Main CLI tool for FamiliarOS agent configuration and familiar management.

Responsibility

Primary user-facing CLI for the FamiliarOS ecosystem. Provides commands for: installing familiars from gallery, configuring projects for Claude/OpenCode/Cursor agents, running MCP server wrapper, executing Claude hooks, and direct familiar interaction (status, react, say).

Design/Patterns

Command Router: main() dispatches to subcommands based on process.argv[2]:

• install <familiar-id> - Install familiar via running app
• configure - Interactive project setup for Claude, OpenCode, or Cursor
• status - Check FamiliarOS desktop app connectivity and print JSON status
• familiars - List installed familiars with flags (default, broken)
• react <reaction> - Send reaction to desktop app
• say <message> [--reaction <reaction>] - Display message on familiar
• mcp - Spawn MCP server (delegates to @familiaros/mcp)
• hook - Execute Claude hook from stdin

Configuration Flow (configureProject):

1. Resolve project directory (symlink/escape checks)
2. Route to agent-specific handler (claude/opencode/cursor)
3. For Claude: Assert availability, list familiars, build MCP config, write hooks
4. For OpenCode: Prepare and write OpenCode config via @familiaros/opencode
5. For Cursor: Configure MCP in .cursor/mcp.json, optional rules in .cursor/rules/familiaros.mdc

Cursor Configuration:

• --with-rules - Install MCP + project rules
• --rules-only - Install only .cursor/rules/familiaros.mdc
• --remove-rules - Remove managed rules file
• Status classification: not_installed, installed, needs_update, conflict, error
• Atomic writes with backup creation

Safety Checks:

• Project path validation (no symlinks, must be directory)
• .claude/.cursor/.opencode directory safety (no symlinks, path containment)
• Settings file atomic writes (temp + rename pattern)
• Shell argument quoting for command injection prevention

Familiar Resolution (resolveConfiguredPet):

• Validates explicit --familiar argument
• Otherwise: fetches installed familiars, interactive TTY prompt
• Validates selected familiar is not broken

Flow

familiaros configure --agent claude --familiar <id> --cwd <dir>
    ↓
resolveProjectDir() → assertSafeProjectHookPath()
    ↓
assertClaudeAvailable() (spawnSync "claude --version")
    ↓
resolveConfiguredPet() → listPets() → pickPet() (interactive)
    ↓
prepareProjectLocalHooks() → Build hook command with marker
    ↓
runClaudeMcpAddJson() → spawnSync "claude mcp add-json ..."
    ↓
writePreparedHooks() → Atomic write to .claude/settings.local.json

familiaros configure --agent cursor --with-rules
    ↓
readCursorMcpConfig() → classifyCursorMcpStatus()
    ↓
readCursorFamiliarOSRules() → classifyCursorRulesStatus()
    ↓
planCursorMcpInstall/Replace() → executeCursorMcpWrite()
    ↓
planCursorRulesInstall/Replace() → executeCursorRulesWrite()

familiaros status
    ↓
createFamiliarOSClient().status() → Print JSON result

Integration Points

Dependencies:

• @familiaros/client - Familiar listing, installation, status, react, say
• @familiaros/claude - Hook management, MCP config
• @familiaros/mcp - MCP server spawning
• @familiaros/opencode - OpenCode project setup
• @familiaros/cursor - Cursor project setup (MCP + rules)

External Commands:

• claude - Claude Code CLI for MCP configuration
• npx - For published package execution

Exports:

• cliPackageName constant
• configureProject(), resolveConfiguredPet() - Programmatic API
• parseConfigureArgs(), parseInstallArgs(), parseReactArgs(), parseSayArgs() - Argument parsing
• createVersionPinnedCliCommand(), createLocalDevCliCommand() - Command builders
• installProjectLocalHooks(), prepareProjectLocalHooks() - Hook installation
• runClaudeMcpAddJson(), createClaudeMcpAddJsonArgs() - MCP integration