20 KiB
20 KiB
FamiliarOS Feature Registry
This is the canonical feature registry for the FamiliarOS working repo. It maps every user-facing capability to the files, branches/PRs, and commits that implement it. It is kept in addition to FEATURES.md and FEATURES_OUR_CHANGES.md so that feature ownership, status, and history can be traced quickly.
- Current branch:
feat/familiaros-rebrand - Current HEAD:
69d3046 - Version:
3.1.0 - Status key:
shipped= in the signed Windows installer;merged= inv3.1.0-integrated;in-review= has a PR branch;experimental= behind a flag or not yet packaged.
1. Companion / Familiar core
| Feature | Status | PR / Branch | Key commits | Key files | Notes |
|---|---|---|---|---|---|
| Tray-first desktop companion | shipped | upstream | — | apps/desktop/src/main.ts |
Baseline from upstream. |
| Default + installed familiars | shipped | upstream | — | apps/desktop/src/familiar-installation.ts |
Baseline. |
| Always-on-top familiar window | shipped | upstream | — | apps/desktop/src/familiar-window.ts |
Baseline. |
| Drag with mouse passthrough | shipped | fix/familiar-window-stability |
11ed7b3 |
apps/desktop/src/familiar-window.ts, apps/desktop/familiar-preload.cjs |
Removes post-drag resize jump; anchors resize around familiar foot/center. |
| Adaptive familiar scale 0.16x–10x | shipped | feat/scale-preset-dropdown |
53b8435 |
apps/desktop/src/app-state-core.ts, apps/desktop/src/renderer/src/main.tsx |
Continuous slider + abbreviated preset dropdown. |
| Scale slider draggable thumb | shipped | pr/scale-slider-draggable |
2472950 |
apps/desktop/src/renderer/src/main.tsx |
CSS thumb styling so slider is grabbable. |
| Scale handle + keyboard nudges | removed/replaced | fix/scale-handle-and-keyboard |
be21907, 26d446f |
apps/desktop/src/familiar-window.ts |
Handle added, then removed in favor of Settings +/- nudge buttons. |
| Multi-screen positioning | shipped | main PR | 08eff41 |
apps/desktop/src/familiar-window.ts |
Uses screen.getDisplayNearestPoint() / clampToNearestWorkArea(). |
| Speech-bubble layout | shipped | main PR + OP2 | 08eff41, 8648cad, f514960 |
apps/desktop/src/familiar-window.ts |
Larger bubbles, top-of-screen flip, responsive max-width for large familiars. |
| Single-click petting | shipped | pr/single-click-petting |
46028c7, refined be580ba |
apps/desktop/familiar-preload.cjs, plugins/official/familiaros.virtual-familiar/index.js |
Single click emits familiar:clicked; double click opens chat. Not a v3.1.0 follow-up fix; pre-existing feature refined by OP1. |
| Virtual-familiar context menu | shipped | pr/virtual-familiar-context-menu + refactor/virtual-familiar-context-menu |
98b7875, ab62d9c, 35e4d74 |
plugins/official/familiaros.virtual-familiar/index.js, plugins/official/familiaros.virtual-familiar/locales/en.json |
HUD moved from triple-click overlay to right-click context menu; care actions reordered/renamed. |
| FamiliarOS rebrand | merged | feat/familiaros-rebrand |
current | repo-wide | App identity, package scopes, plugin IDs, state filenames, preload names, and user-facing strings updated from OpenPets to FamiliarOS. |
| Custom Familiar name | merged | feat/familiaros-rebrand |
current | apps/desktop/src/app-state.ts, apps/desktop/src/tray.ts, apps/desktop/src/renderer/src/main.tsx |
User-defined name for the default Familiar appears in tray tooltip and context menu. |
| Curated familiar catalog safety | merged | feat/familiaros-rebrand |
current | apps/desktop/src/catalog.ts, apps/desktop/src/catalog-validation.ts, apps/desktop/catalog.v2.fixture.json, apps/desktop/contracts/catalog-fixture.contract.ts |
Curated catalog metadata now preserves original / featured / category fields end-to-end, uses IP-safer FamiliarOS fixture familiars, and keeps surfaceable pagination totals aligned with the real searchable set. |
| Control Center bridge hardening | merged | feat/familiaros-rebrand |
current | apps/desktop/src/renderer/src/main.tsx, apps/desktop/tests/plugin-ui-static.test.ts |
The Control Center API bridge now resolves to a required ControlCenterApi once at startup instead of leaking optionality through the whole renderer, and the static validation was updated to the stricter bridge shape. |
| Control Center route modularization | merged | feat/familiaros-rebrand |
current | apps/desktop/src/renderer/src/main.tsx, apps/desktop/src/renderer/src/control-center/*.tsx, apps/desktop/src/check-packaging-contract.ts, apps/desktop/tests/plugin-ui-static.test.ts |
The renderer shell now routes into dedicated dashboard, familiars, settings, integrations, and plugins modules, with shared bridge/types/UI extracted into control-center/shared.tsx so future Control Center work no longer has to funnel through one giant file. |
2. Floating chat / prompt window
| Feature | Status | PR / Branch | Key commits | Key files | Notes |
|---|---|---|---|---|---|
| Floating prompt window | shipped | main PR | 08eff41 |
apps/desktop/src/prompt-window.ts, apps/desktop/prompt-window-preload.cjs |
Frameless, always-on-top, compact/expanded modes. |
| Chat history list UI | shipped | main PR | 08eff41 |
apps/desktop/src/prompt-window.ts |
Styled per-entry cards with role badges/timestamps. |
| Multi-conversation support | shipped | main PR | 08eff41 |
apps/desktop/src/prompt-window.ts, apps/desktop/src/openapi-chat.ts |
Create/switch/delete conversations. |
| Attachments in prompt window | shipped | op6/chat-file-attachments + fix/prompt-window-hardening |
ccb3224, c226280 |
apps/desktop/src/prompt-window.ts |
File picker, attachment chips, base64 data-URL reading. |
| Auto-growing textarea | shipped | fix/prompt-window-hardening |
c226280 |
apps/desktop/src/prompt-window.ts |
Textarea fills resized window. |
| Enter sends / Ctrl+Enter newline | shipped | fix/prompt-window-hardening |
c226280 |
apps/desktop/src/prompt-window.ts |
Keyboard behavior. |
| Packaged-build inline-script newline fix | shipped | fix/prompt-window chain |
61da20d |
apps/desktop/src/prompt-window.ts |
Escapes \n in generated inline script. |
| Store attachments in Knowledge Store | shipped | pr/knowledge-store-hardening |
f514960 |
apps/desktop/src/prompt-window.ts, apps/desktop/prompt-window-preload.cjs |
Toolbar button stores each attachment into Knowledge Store. |
3. OpenAPI BYOK chat
| Feature | Status | PR / Branch | Key commits | Key files | Notes |
|---|---|---|---|---|---|
| OpenAPI chat service | shipped | main PR | 08eff41 |
apps/desktop/src/openapi-chat.ts |
Main-process chat with responses + chat/completions. |
| Provider presets | shipped | main PR | 08eff41 |
apps/desktop/src/openapi-chat.ts, apps/desktop/src/renderer/src/main.tsx |
OpenAI, OpenRouter, Azure, LiteLLM, vLLM, Moonshot/Kimi, custom. |
| Secure credential storage | shipped | main PR | 08eff41 |
apps/desktop/src/openapi-chat.ts |
safeStorage with plain fallback. |
| Familiar character / system prompt | shipped | main PR | 08eff41 |
apps/desktop/src/renderer/src/main.tsx |
User-editable character field. |
| Base-instructions toggle | shipped | main PR | 08eff41 |
apps/desktop/src/renderer/src/main.tsx |
Include/exclude default FamiliarOS behavior instructions. |
| Knowledge context injection | shipped | pr/knowledge-store-hardening |
f514960 |
apps/desktop/src/openapi-chat.ts, apps/desktop/src/knowledge-store.ts |
Relevant stored files appended to system instructions. |
4. Memory system
| Feature | Status | PR / Branch | Key commits | Key files | Notes |
|---|---|---|---|---|---|
| Local memory engine | shipped | main PR | 08eff41 |
apps/desktop/src/familiaros-memory.ts |
JSON store + markdown mirror. |
| Memory capture patterns | shipped | main PR | 08eff41 |
apps/desktop/src/familiaros-memory.ts |
remember, my name is, I prefer, etc. |
| Memory kinds + importance + tags | shipped | main PR | 08eff41 |
apps/desktop/src/familiaros-memory.ts |
preference, identity, fact, note. |
| In-app memory viewer | shipped | main PR | 08eff41 |
apps/desktop/src/renderer/src/main.tsx |
Search, edit, delete. |
| Memory hardening | shipped | pr/memory-hardening |
2de484d |
apps/desktop/src/openapi-chat.ts, apps/desktop/src/familiaros-memory.ts |
Capture logged + fails safely; recall-intent fallback. |
| Chat-history memory | shipped | main PR | 08eff41 |
apps/desktop/src/openapi-chat.ts, apps/desktop/src/familiaros-memory.ts |
Cross-conversation excerpts injected into prompt. |
5. Knowledge Store
| Feature | Status | PR / Branch | Key commits | Key files | Notes |
|---|---|---|---|---|---|
| File + memory knowledge repository | shipped | pr/knowledge-store-hardening |
4aff369, f514960 |
apps/desktop/src/knowledge-store-core.ts, apps/desktop/src/knowledge-store.ts |
Electron-free core + wrapper. |
| Text extraction + MIME inference | shipped | pr/knowledge-store-hardening |
4aff369 |
apps/desktop/src/knowledge-store-core.ts |
Text-like files only; non-text placeholder. |
| Relevance search + scoring | shipped | pr/knowledge-store-hardening |
4aff369 |
apps/desktop/src/knowledge-store-core.ts |
Token/phrase overlap, recency, size penalty; false-positive guard added. |
| Settings Knowledge Store tab | shipped | pr/knowledge-store-hardening |
f514960 |
apps/desktop/src/renderer/src/main.tsx, apps/desktop/control-center-preload.cjs |
Upload, list, search, delete, add memory. |
| Prompt-window store button | shipped | pr/knowledge-store-hardening |
f514960 |
apps/desktop/src/prompt-window.ts, apps/desktop/prompt-window-preload.cjs |
Store attachments from chat composer. |
| Unit tests | shipped | pr/knowledge-store-hardening |
4aff369, d8650a9 |
apps/desktop/tests/knowledge-store.test.ts |
Deterministic Node tests. |
| UTF-8 fallback | shipped | pr/knowledge-store-hardening |
4aff369 |
apps/desktop/src/knowledge-store-core.ts |
TextDecoder fallback when Buffer.isUtf8 missing. |
6. MCP edition
6a. FamiliarOS MCP server
| Feature | Status | PR / Branch | Key commits | Key files | Notes |
|---|---|---|---|---|---|
| MCP server package | shipped | upstream / main PR | 3f8fa1a+ |
packages/mcp/src/server.ts, packages/mcp/src/tools.ts |
familiaros MCP server. |
| Status / react / say tools | shipped | upstream | — | packages/mcp/src/tools.ts |
Baseline. |
| Memory tools (list/search/store/forget) | shipped | upstream | — | packages/mcp/src/tools.ts |
Baseline. |
| Lease routing + default-familiar fallback | shipped | upstream | — | packages/mcp/src/server.ts |
Baseline. |
6b. MCP Tool Servers (built-in chat)
| Feature | Status | PR / Branch | Key commits | Key files | Notes |
|---|---|---|---|---|---|
| Internal stdio MCP client | shipped | main PR | 08eff41 |
apps/desktop/src/mcp-chat-client.ts |
Spawns tool servers inside floating chat. |
| Top-level "MCP Tool Servers" panel | shipped | main PR | current | apps/desktop/src/renderer/src/main.tsx |
Central place to activate tool servers for built-in chat, independent of external agents. |
| Tool activation UI | shipped | main PR | 08eff41 / current |
apps/desktop/src/renderer/src/main.tsx |
Multi-select chips by tier. |
| Supported tool servers | shipped | main PR | 08eff41 |
apps/desktop/src/mcp-chat-client.ts |
filesystem, terminal, memory, fetch-web, sequential-thinking, playwright, git, github, docker, sqlite. |
| ReAct-style tool loop | shipped | main PR | 08eff41 |
apps/desktop/src/mcp-chat-client.ts, apps/desktop/src/openapi-chat.ts |
Max 5 iterations. |
6c. FamiliarOS MCP Server (external-agent bridge)
| Feature | Status | PR / Branch | Key commits | Key files | Notes |
|---|---|---|---|---|---|
| Central "FamiliarOS MCP Server" panel | shipped | main PR | current | apps/desktop/src/renderer/src/main.tsx, apps/desktop/src/agent-setup.ts |
Configures command mode, node path, familiar routing, test server, and MCP JSON for external hosts. |
| Server health test | shipped | main PR | current | apps/desktop/src/agent-setup.ts, apps/desktop/src/windows.ts |
--version smoke test via IPC. |
| MCP JSON copy | shipped | main PR | current | apps/desktop/src/renderer/src/main.tsx |
One-click copy of the mcpServers.familiaros entry. |
6d. MCP Toolkit Guide
| Feature | Status | PR / Branch | Key commits | Key files | Notes |
|---|---|---|---|---|---|
| Toolkit panel in Integrations | shipped | main PR | 08eff41 |
apps/desktop/src/renderer/src/main.tsx, apps/desktop/src/renderer/src/mcp-toolkit-catalog.ts |
Curated, permission-aware reference surface. |
| Tiered family browser | shipped | main PR | 08eff41 |
apps/desktop/src/renderer/src/mcp-toolkit-catalog.ts |
Starter / Terminal & Systems / Advanced. |
| Install orchestration | shipped | main PR | 08eff41 |
apps/desktop/src/mcp-toolkit-installer.ts |
Persistent bundles for Claude/Codex baselines. |
| Command-source labels | shipped | main PR | 08eff41 |
apps/desktop/src/renderer/src/mcp-toolkit-catalog.ts |
Stable release / shipped with app / local build. |
7. Agent integrations
| Feature | Status | PR / Branch | Key commits | Key files | Notes |
|---|---|---|---|---|---|
| Claude Code integration | shipped | upstream / main PR | — | packages/claude/ |
Baseline. |
| OpenCode integration | shipped | upstream / main PR | — | packages/opencode/ |
Baseline. |
| Cursor integration | shipped | upstream / main PR | — | packages/cursor/ |
Baseline. |
| Pi guidance | shipped | upstream / main PR | — | packages/pi/ |
Baseline. |
8. Plugins / modding
| Feature | Status | PR / Branch | Key commits | Key files | Notes |
|---|---|---|---|---|---|
| Plugin catalog / install / enable | shipped | upstream | — | apps/desktop/src/plugin-*.ts |
Baseline. |
| Official plugin suite | shipped | upstream | — | plugins/official/ |
Baseline: focus-buddy, reminders, launch-buddy, water-reminder, mood-check-in, day-routine, magic-8-ball, fortune-cookie, virtual-familiar. |
| Virtual-familiar plugin bundling | shipped | pr/virtual-familiar-context-menu |
98b7875 |
plugins/official/familiaros.virtual-familiar/index.js |
Re-enabled after temporary disable. |
9. Text-to-Speech (Phase 2)
| Feature | Status | PR / Branch | Key commits | Key files | Notes |
|---|---|---|---|---|---|
| TTS settings panel | merged | TTS Phase 2 / v3.1.0-integrated |
current | apps/desktop/src/renderer/src/main.tsx |
Provider, voice, speed, model, endpoint preset, credential, and test/stop UI. |
| System voice playback | merged | TTS Phase 2 / v3.1.0-integrated |
current | apps/desktop/familiar-preload.cjs, apps/desktop/prompt-window-preload.cjs |
OS speech engine via Web Speech API; rate 0.5×–2.0× and voice-name matching. |
| Cloud TTS providers | merged | TTS Phase 2 / v3.1.0-integrated |
current | apps/desktop/src/tts-engine.ts |
OpenAI TTS, ElevenLabs, and OpenAI-compatible endpoints. |
| Piper local TTS | merged | TTS Phase 2 / v3.1.0-integrated |
current | apps/desktop/src/tts-engine.ts |
Spawns local piper binary; WAV magic-byte validation. |
| Credential storage | merged | TTS Phase 2 / v3.1.0-integrated |
current | apps/desktop/src/tts-credentials.ts |
Per-provider API key stored with safeStorage; plain fallback. |
| Endpoint presets | merged | TTS Phase 2 / v3.1.0-integrated |
current | apps/desktop/src/tts-catalog.ts |
OpenRouter, LiteLLM, WaveSpeedAI, Custom. |
| TTS service & quiet hours | merged | TTS Phase 2 / v3.1.0-integrated |
current | apps/desktop/src/tts-service.ts |
Shared dispatcher; skips speech during quiet hours. |
| TTS IPC handlers | merged | TTS Phase 2 / v3.1.0-integrated |
current | apps/desktop/src/windows.ts |
familiaros:get-tts-settings, familiaros:get-tts-voices, familiaros:save-tts-credential, familiaros:test-tts, familiaros:tts-stop. |
| TTS engine tests | merged | TTS Phase 2 / v3.1.0-integrated |
current | apps/desktop/tests/tts-engine.test.ts |
Provider catalog, defaults, and preset validation. |
| Plugin voice bridge | merged | TTS Phase 2 / v3.1.0-integrated |
current | apps/desktop/src/plugin-voice.ts |
voice:speak permission lets plugins speak through the same pipeline. |
10. Packaging / release
| Feature | Status | PR / Branch | Key commits | Key files | Notes |
|---|---|---|---|---|---|
| Electron Builder setup | shipped | upstream / pr/packaging-and-docs |
743163d |
apps/desktop/electron-builder.yml |
Windows NSIS + portable, Linux AppImage/deb/rpm/tar.gz, macOS dmg/zip. |
| asarUnpack for preloads | shipped | pr/packaging-and-docs |
743163d |
apps/desktop/electron-builder.yml |
Preload scripts unpacked for sandboxed packaged builds. |
| Packaging contract | shipped | pr/packaging-and-docs + pr/knowledge-store-hardening |
743163d, f514960 |
apps/desktop/src/check-packaging-contract.ts |
Assertions for preload presence, bubble CSS, etc. |
| Windows code signing | shipped | TTS Phase 2 / v3.1.0-integrated |
bb758e9 build |
apps/desktop/dist-electron/ |
Signed with host certificate via signtool.exe. |
| Signed installer delivery | shipped | TTS Phase 2 / v3.1.0-integrated |
bb758e9 |
C:\familiaros-build\apps\desktop\dist-electron\FamiliarOS-3.1.0-win-x64-setup.exe |
SHA256: 79b0c01b08d6121f54675c176a5d7c22d1f8e3591b191d760aae6d6300d4b5bb. |
Removed / replaced capabilities
| Capability | What happened | Replacement | Commits |
|---|---|---|---|
| On-familiar drag-to-resize handle | Removed | Settings scale slider + +/- nudge buttons + keyboard arrows |
4aa60a3, be21907, 26d446f |
| Virtual-familiar triple-click HUD overlay | Removed | Right-click context menu Familiar Status | 4aa60a3, 98b7875 |
| Triple-click familiar action | Removed | Single-click petting + double-click chat | 46028c7 |
Documentation files
| File | Purpose |
|---|---|
FEATURES.md |
Full feature inventory for the fork. |
FEATURES_OUR_CHANGES.md |
Isolated list of only our additions. |
FEATURE_REGISTRY.md |
This file — feature-to-branch/commit/files mapping. |
PULL_REQUEST.md |
Main PR description for the big feature set. |
README_OUR_CHANGES.md |
Isolated user-facing README of additions. |
docs/pull-requests/FAMILIAROS_3_1_0_FIXES_PULL_REQUESTS.md |
Categorized fix PRs for v3.1.0. |
docs/pull-requests/FAMILIAROS_3_1_0_MOD_NICHE_PULL_REQUESTS.md |
Same fixes organized by mod niche. |
docs/pull-requests/OP_1_6_PULL_REQUESTS.md |
OP1–OP6 user-reported tweak branches. |
docs/pull-requests/PR_SINGLE_CLICK_PETTING.md |
Single-click petting PR (pre-v3.1.0). |
docs/pull-requests/PR_VIRTUAL_PET_CONTEXT_MENU.md |
Virtual-familiar context-menu PR (pre-v3.1.0). |
docs/pull-requests/PR_MEMORY_HARDENING.md |
Memory hardening PR. |
docs/pull-requests/PR_BUBBLE_CLIP_FIX.md |
Bubble clip fix PR. |
docs/pull-requests/PR_SCALE_SLIDER_DRAGGABLE.md |
Scale slider draggable thumb PR. |
docs/pull-requests/PR_PACKAGING_AND_DOCS.md |
Packaging/docs PR. |
docs/pull-requests/PROMPT_WINDOW_PACKAGED_BUILD_FIX_2026-06-15.md |
Prompt-window packaged-build fix root cause. |
docs/pull-requests/PR_TTS_PHASE_2.md |
Text-to-Speech Phase 2 PR description. |
docs/pr-chat-memory-mcp-toolkit.md |
Floating chat + memory + MCP toolkit explainer. |
Branches on this repo
main— upstream-aligned baseline.v3.1.0-integrated— integration branch with all v3.1.0 work plus TTS Phase 2 (HEADbb758e9).feat/scale-preset-dropdown,fix/familiar-window-stability,fix/prompt-window-hardening,fix/prompt-window-signed-build,fix/scale-handle-and-keyboard,refactor/virtual-familiar-context-menu— topic branches from the six original PRs.op1/familiar-drag-threshold…op6/chat-file-attachments— user-reported tweak branches.pr/bubble-clip-fix,pr/memory-hardening,pr/packaging-and-docs,pr/scale-slider-draggable,pr/single-click-petting,pr/virtual-familiar-context-menu— PR branch pointers.pr/knowledge-store-hardening— Knowledge Store PR branch pointer (atf514960).