# 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/codemap.md) |
| `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/codemap.md) |
| `apps/desktop/contracts/` | Desktop public-boundary contract tests for catalog fixtures, local IPC protocol behavior, and plugin manifest schema validation. | [View Map](apps/desktop/contracts/codemap.md) |
| `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/codemap.md) |
| `apps/desktop/src/renderer/` | Vite renderer workspace for the sandboxed React/Tailwind Control Center bundle. | [View Map](apps/desktop/src/renderer/codemap.md) |
| `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/src/renderer/src/codemap.md) |
| `apps/desktop/scripts/` | Desktop package cleanup and local release automation scripts. | [View Map](apps/desktop/scripts/codemap.md) |
| `packages/` | Publishable npm package workspace for shared protocol, CLI, MCP, and coding-agent integrations. | [View Map](packages/codemap.md) |
| `packages/agent-events/` | Shared agent speech/event message pools and validation utilities. | [View Map](packages/agent-events/codemap.md) |
| `packages/agent-events/src/` | Source implementation for agent event messages. | [View Map](packages/agent-events/src/codemap.md) |
| `packages/claude/` | Claude Code integration package for hooks, MCP setup, and settings/memory management. | [View Map](packages/claude/codemap.md) |
| `packages/claude/src/` | Claude Code hook handlers, hook settings, CLI integration, and exported setup APIs. | [View Map](packages/claude/src/codemap.md) |
| `packages/client/` | IPC client package that discovers and communicates with the desktop app. | [View Map](packages/client/codemap.md) |
| `packages/client/contracts/` | Client protocol contract tests for discovery, endpoint validation, responses, and familiar result parsing. | [View Map](packages/client/contracts/codemap.md) |
| `packages/client/src/` | Protocol definitions, discovery logic, public client API, and smoke entry points. | [View Map](packages/client/src/codemap.md) |
| `packages/cli/` | User-facing FamiliarOS CLI package. | [View Map](packages/cli/codemap.md) |
| `packages/cli/src/` | CLI command parsing and orchestration across client, Claude, OpenCode, and MCP packages. | [View Map](packages/cli/src/codemap.md) |
| `packages/cursor/` | Cursor editor integration package for managed MCP configuration and project-local rules. | [View Map](packages/cursor/codemap.md) |
| `packages/cursor/src/` | Cursor config/rules planning, status classification, safe writes, previews, and validation checks. | [View Map](packages/cursor/src/codemap.md) |
| `packages/install-familiar/` | Standalone installer package for gallery/catalog familiars. | [View Map](packages/install-familiar/codemap.md) |
| `packages/install-familiar/src/` | Familiar installation command implementation. | [View Map](packages/install-familiar/src/codemap.md) |
| `packages/mcp/` | MCP server package exposing FamiliarOS tools to compatible agents. | [View Map](packages/mcp/codemap.md) |
| `packages/mcp/src/` | MCP server bootstrap, argument parsing, tool registration, and executable validation helpers. | [View Map](packages/mcp/src/codemap.md) |
| `packages/opencode/` | OpenCode editor integration package with plugin runtime and global setup helpers. | [View Map](packages/opencode/codemap.md) |
| `packages/opencode/src/` | OpenCode plugin, config mutation, previews, status, and project/global setup modules. | [View Map](packages/opencode/src/codemap.md) |
| `packages/pi/` | Pi coding-agent integration package with extension runtime and slash command support. | [View Map](packages/pi/codemap.md) |
| `packages/pi/src/` | Pi extension entry point, event classification, FamiliarOS command parsing, and validation checks. | [View Map](packages/pi/src/codemap.md) |
| `packages/familiar-format/` | Minimal package marker/type interface for FamiliarOS familiar package identity. | [View Map](packages/familiar-format/codemap.md) |
| `packages/familiar-format/src/` | Marker source export for familiar-format package consumers. | [View Map](packages/familiar-format/src/codemap.md) |
| `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.