scriptoriumadmin/openpetswithchatandmcp
1
0
Fork 0
Code Issues Pull requests 6 Projects Releases Packages Wiki Activity Actions

docs: FamiliarOS marketing copy, rebrand docs, and custom Familiar name

Browse source 
- Rewrite README.md hero and feature sections with FamiliarOS manifest copy.
- Update README_OUR_CHANGES.md, FEATURES.md, FEATURES_OUR_CHANGES.md,
  PULL_REQUEST.md, and FEATURE_REGISTRY.md with rebrand and custom naming.
- Rename packages/install-familiar/src/check-install-pet.ts to
  check-install-familiar.ts to match rebrand and package test script.
- Custom Familiar name already wired through app-state, tray, Settings UI,
  and i18n; docs now describe it.
This commit is contained in:
OpenPets Dev 2026-06-17 01:48:40 +00:00
parent 6ab3bb64d8
commit a030240467
7 changed files with 168 additions and 336 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
FEATURES.md
View file

@ -77,6 +77,13 @@ It combines:
- Feed, play, and nap actions are also available from the familiar context menu
- Automatic nudges when a stat gets low
## Custom Familiar Name
- Settings → General includes a **Familiar name** field for the default Familiar
- The name persists in `familiaros-state.json` and is applied through `validatePreferencePatch`
- The chosen name appears in the tray tooltip and the tray context menu
- The menu falls back to the Familiar's display name or "Built-in Familiar" when no custom name is set
## Floating Chat Surface
- Double-click the familiar to open a floating prompt window
@ -188,7 +195,9 @@ It combines:
- Invalid-file rejection: empty files, non-Buffer data, missing names, and path-traversal names
- Electron-free core class (`knowledge-store-core.ts`) for deterministic Node unit tests
## FamiliarOS MCP Server
## FamiliarOS MCP Server (External-Agent Bridge)
This MCP server exposes your Familiar to Claude Code, Cursor, OpenCode, Codex CLI, or any other MCP-capable host. It is a small, controlled bridge: external agents can make your Familiar react, speak a safe bubble, or read/write memory, but they do not get unrestricted access to your desktop.
- Local IPC discovery file and per-run token flow
- MCP server for FamiliarOS desktop control
@ -228,7 +237,9 @@ It combines:
- Agent-specific command path overrides (Claude command, OpenCode command)
- Node command path centralized in the FamiliarOS MCP Server panel
## MCP Tool Servers (Built-in Chat)
## MCP Tool Servers (Built-in Chat Tools)
The MCP Tool Servers panel gives the built-in floating chat the ability to do real work on your local machine. It is separate from the external-agent bridge and works without any external agent installed.
- Top-level **MCP Tool Servers** panel in Control Center → Integrations
- Multi-select MCP tool activation for the built-in floating chat
@ -240,7 +251,7 @@ It combines:
## Curated MCP Toolkit Surface
The control-center Integrations page now also includes a curated **Curated MCP Toolkit** panel. This does not pretend to be a full unsafe one-click installer for the whole MCP ecosystem. Instead, it provides a practical, permission-aware reference surface with copyable snippets and docs links.
The control-center Integrations page includes a **Curated MCP Toolkit** panel. It is not an automatic installer; it is a permission-aware reference that explains what popular MCP tools do, what permissions they need, and how to set them up manually or as a persistent bundle in supported hosts. Each entry includes copy-paste snippets and guidance so you can adopt the MCP ecosystem deliberately.
### Starter Stack In The Toolkit

17
FEATURES_OUR_CHANGES.md
View file

@ -35,6 +35,13 @@ This document lists only the features, UI surfaces, and capabilities added by ou
- Character prompt persists in app state and applies to future assistant replies.
- Base instructions toggle to include/exclude the default FamiliarOS behavior instructions in every chat.
## Custom Familiar Name
- Settings → General includes a user-editable **Familiar name** field for the default Familiar.
- The name persists in app state (`familiaros-state.json`) and is applied through `validatePreferencePatch`.
- The chosen name appears in the tray tooltip and tray context menu.
- Falls back to the Familiar's display name or "Built-in Familiar" when no custom name is set.
## Familiar Text-to-Speech (Phase 2)
- Settings > **Text-to-Speech** panel for the familiar and floating chat.
@ -83,14 +90,10 @@ This document lists only the features, UI surfaces, and capabilities added by ou
## Curated MCP Toolkit Integration
- Curated MCP Toolkit panel inside Control Center → Integrations.
- Permission-aware reference surface, not an automatic installer.
- Each entry explains what the tool does, what permissions it needs, and how to set it up manually or as a persistent bundle in supported hosts.
- Multi-select chips by tier (Starter, Terminal & Systems, Advanced).
- Command Source labels clarify where tools come from:
- Stable release (npm)
- Shipped with this app
- Local source build
- Install Choice descriptions:
- Manual Setup = copy-paste commands
- Persistent Full Access = auto-register into Claude/Codex
- Copy-paste snippets and docs links for deliberate adoption.
- Removed redundant Curated Stack section in favor of direct tiered selection.
## Knowledge Store

4
FEATURE_REGISTRY.md
View file

@ -3,7 +3,7 @@
This is the canonical feature registry for the VectorShell working fork of FamiliarOS. 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:** `v3.1.0-integrated`
- **Current HEAD:** `bb758e9`
- **Current HEAD:** `ef722ee`
- **Version:** `3.1.0`
- **Status key:** `shipped` = in the signed Windows installer; `merged` = in `v3.1.0-integrated`; `in-review` = has a PR branch; `experimental` = behind a flag or not yet packaged.
@ -24,6 +24,8 @@ This is the canonical feature registry for the VectorShell working fork of Famil
| 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. |
## 2. Floating chat / prompt window

21
PULL_REQUEST.md
View file

@ -1,6 +1,6 @@
# Pull Request: Floating Chat, Memory, Knowledge Store, MCP Servers, Curated MCP Toolkit, TTS Phase 2 & Familiar Sizing
# Pull Request: FamiliarOS Rebrand, Custom Familiar Naming, Floating Chat, Memory, Knowledge Store, MCP Servers, Curated MCP Toolkit, TTS Phase 2 & Familiar Sizing
**Title:** feat(desktop): add floating chat, local memory, Knowledge Store, MCP Tool Servers, FamiliarOS MCP Server panel, Curated MCP Toolkit, Text-to-Speech Phase 2, expanded familiar sizing, and multi-screen support
**Title:** feat(desktop): rebrand to FamiliarOS, add custom Familiar naming, floating chat, local memory, Knowledge Store, MCP Tool Servers, FamiliarOS MCP Server panel, Curated MCP Toolkit, Text-to-Speech Phase 2, expanded familiar sizing, and multi-screen support
**Author:** VectorShell working fork
**Base:** upstream `main` at `cba81b7`
@ -10,7 +10,7 @@
## Summary
This PR adds a complete in-app chat layer, a durable local memory system, interactive MCP tool activation, and several companion-quality improvements to the desktop familiar. Every change is additive and preserves existing MCP/agent integration behavior.
This PR adds the FamiliarOS rebrand from OpenPets, a user-editable custom Familiar name, a complete in-app chat layer, a durable local memory system, interactive MCP tool activation, and several companion-quality improvements to the desktop familiar. Every change is additive and preserves existing MCP/agent integration behavior.
## Motivation
@ -21,6 +21,17 @@ This PR adds a complete in-app chat layer, a durable local memory system, intera
## What changed
### FamiliarOS rebrand
- Renamed the app, packages, plugin IDs, state files, preload files, and user-facing strings from OpenPets / pets to FamiliarOS / Familiars.
- Updated `README.md`, `FEATURES.md`, `README_OUR_CHANGES.md`, `FEATURES_OUR_CHANGES.md`, and `PULL_REQUEST.md` to reflect the new brand and voice.
### Custom Familiar name
- Added a **Familiar name** field in Settings → General.
- The name is persisted in `familiaros-state.json`, validated through `validatePreferencePatch`, and shown in the tray tooltip and context menu.
- Falls back to the Familiar's display name or "Built-in Familiar" when no custom name is set.
### New surfaces
- **Floating Prompt Window** (`apps/desktop/src/prompt-window.ts`)
@ -82,6 +93,7 @@ This PR adds a complete in-app chat layer, a durable local memory system, intera
- OpenAPI chat: endpoint preset, model, credential, theme, base-instructions toggle.
- Moonshot/Kimi endpoint preset.
- Familiar character / system prompt field.
- **Familiar name** field for the default Familiar.
- Memory viewer with search/edit/delete.
- **Knowledge Store** tab: upload files, search stored knowledge, delete files, and add manual memory entries.
@ -157,7 +169,8 @@ All existing tests pass. Additional manual verification:
10. Add an OpenAI TTS key, select a voice, click **Speak** — audio should play through the familiar window.
11. Store a `.txt` file in Settings > Knowledge Store and ask the assistant about its content — the reply should reference the stored file.
12. Right-click the familiar → choose Virtual Familiar ▸ Feed/Play/Familiar/Nap; stats update and the context menu reflects the new values.
13. Change display — familiar should stay on the display it is currently near.
13. Change the **Familiar name** in Settings → General; the tray tooltip and tray menu should immediately show the new name.
14. Change display — familiar should stay on the display it is currently near.
## Backwards compatibility

407
README.md
View file

@ -1,17 +1,21 @@
<p align="center">
<img src="assets/familiaros.png" alt="FamiliarOS - pixel art desktop companion" width="100%" />
<img src="assets/familiaros.png" alt="FamiliarOS" width="100%" />
</p>
<p align="center">
<strong>A tiny desktop companion that keeps you company.</strong>
<strong>Your AI Companion That Lives With You.</strong>
</p>
<p align="center">
A playful familiar that lives on your desktop, keeps you company, and can grow with bundled abilities and developer integrations.
Most AI assistants live in a browser tab. Most AI agents live in a terminal. <strong>FamiliarOS lives on your desktop.</strong>
</p>
<p align="center">
<sub>This branch also includes a <strong>floating chat surface</strong>, <strong>local memory</strong>, <strong>Knowledge Store</strong>, <strong>MCP Tool Servers</strong>, an <strong>FamiliarOS MCP Server</strong> panel, a <strong>Curated MCP Toolkit</strong>, <strong>Text-to-Speech (Phase 2)</strong>, and <strong>expanded familiar sizing</strong>. See <code>FEATURES.md</code>, <code>FEATURE_REGISTRY.md</code>, and <code>PULL_REQUEST.md</code> for details.</sub>
At its heart is your <strong>Familiar</strong>: a persistent AI companion that remembers who you are, learns your preferences, speaks with you, helps with everyday tasks, and can grow into a powerful local agent with access to tools, knowledge, and workflows.
</p>
<p align="center">
<sub>This fork includes a <strong>floating chat surface</strong>, <strong>local memory</strong>, <strong>Knowledge Store</strong>, <strong>MCP Tool Servers</strong>, a <strong>FamiliarOS MCP Server</strong> panel, a <strong>Curated MCP Toolkit</strong>, <strong>Text-to-Speech</strong>, <strong>Familiar naming</strong>, and <strong>expanded familiar sizing</strong>. See <code>FEATURES.md</code>, <code>FEATURE_REGISTRY.md</code>, and <code>PULL_REQUEST.md</code> for details.</sub>
</p>
<p align="center">
@ -27,18 +31,37 @@
</p>
</div>
---
## What makes FamiliarOS different
FamiliarOS is a **local-first AI companion platform**.
Create your own Familiar: a persistent desktop companion with memory, voice, knowledge, and powerful agent capabilities.
Your Familiar can:
- 🧠 **Remember** preferences, facts, notes, identities, and important details across sessions.
- 🗣 **Speak and listen** with system voices, OpenAI, ElevenLabs, Piper, or OpenAI-compatible TTS providers.
- 📚 **Learn from your files** through the searchable Knowledge Store.
- 🔧 **Use MCP tools** such as filesystem access, terminal commands, web retrieval, Git, GitHub, Docker, Playwright, SQLite, memory systems, and reasoning tools.
- 💬 **Chat** through an always-on-top floating window.
- 🐾 **Interact** as a virtual companion with reactions, animations, and care actions.
Part virtual companion. Part AI assistant. Part autonomous agent. Entirely yours.
> **The best AI isn't just a tool you open. It's a companion that stays.**
---
## 2-minute Quick Start
Download and launch the desktop app from [FamiliarOS Releases](https://github.com/alvinunreal/familiaros/releases/latest). A companion familiar appears immediately; bundled abilities make it feel alive without requiring an agent setup.
Download and launch the desktop app from [FamiliarOS Releases](https://github.com/verticaltension/familiaros/releases/latest). A companion Familiar appears immediately; bundled abilities make it feel alive without requiring an agent setup.
If you also want coding-agent integration, install the FamiliarOS Agent Skill with [skills.sh](https://skills.sh/):
```bash
npx skills add alvinunreal/familiaros --skill familiaros
npx skills add verticaltension/familiaros --skill familiaros
```
Then open Claude Code, OpenCode, Codex, or another skill-aware agent and say:
@ -50,48 +73,67 @@ Use the FamiliarOS skill. Install FamiliarOS for me, connect this agent, and ver
For project setup, open your agent inside the repo and say:
```text
Use the FamiliarOS skill. Help me choose or install a familiar, configure it for this project, and verify the project integration.
Use the FamiliarOS skill. Help me choose or install a Familiar, configure it for this project, and verify the project integration.
```
Useful prompts:
```text
Use the FamiliarOS skill. Configure this project for Claude Code with a familiar.
Use the FamiliarOS skill. Configure this project for OpenCode with a familiar.
Use the FamiliarOS skill. Configure this project for Claude Code with a Familiar.
Use the FamiliarOS skill. Configure this project for OpenCode with a Familiar.
Use the FamiliarOS skill. Debug why familiaros_status is unavailable.
```
## Star FamiliarOS
---
Here is an extra GIF of me starring my own repo to encourage you to do the same. If FamiliarOS makes your coding setup a little more fun, please give the repo a star.
## Create your Familiar
A Familiar is more than a chatbot. More than a virtual companion. More than an assistant.
A Familiar is a persistent AI companion that lives on your desktop, remembers what matters, learns how you work, and grows alongside you.
- **Give it a personality.** Set a character prompt in Settings.
- **Name it.** Your Familiar appears by name in the tray and menus.
- **Let it remember.** Memory is captured automatically from chat and can be edited or searched in Settings.
- **Upload knowledge.** Drop files into the Knowledge Store and your Familiar can retrieve relevant information during future conversations.
- **Talk to it.** Text or voice — your Familiar can listen and speak back.
You stop thinking about models, providers, APIs, prompts, and infrastructure. Instead you think:
> "My Familiar reminded me."
> "My Familiar found that file."
> "My Familiar summarized that document."
> "My Familiar remembers how I like things done."
The best software creates habits. The best companions create relationships.
---
## What FamiliarOS can do
- **Desktop companion** — a small Familiar that idles, reacts, and gives FamiliarOS a friendly presence even before developer tools are configured.
- **Bundled abilities** — first-party plugins add ambient check-ins, break nudges, playful Familiar actions, focus timers, safe little walks, and optional developer notifications.
- **Floating chat** — double-click your Familiar to open an always-on-top chat window with BYOK OpenAPI-compatible providers, conversation history, and optional MCP Tool Server activation.
- **Local memory** — the Familiar remembers facts, preferences, and notes across sessions.
- **Knowledge Store** — upload documents, notes, code, and reference material; your Familiar retrieves relevant context automatically.
- **Voice** — system voices, OpenAI TTS, ElevenLabs, Piper, or OpenAI-compatible endpoints for speech input and output.
- **MCP Tool Servers** — activate filesystem, terminal, web, Git, GitHub, Docker, Playwright, SQLite, memory, and reasoning tools directly from chat.
- **FamiliarOS MCP Server** — external agents (Claude Code, Cursor, OpenCode, Codex CLI) can control your Familiar through a safe, limited tool surface.
- **Curated MCP Toolkit** — a permission-aware reference surface for adopting the broader MCP ecosystem safely.
- **Virtual-Familiar status** — hunger, energy, happiness, bond, mood, and level live in the right-click context menu, never blocking chat clicks.
- **Privacy-conscious by design** — automatic hook speech is static and local; prompts, code, logs, command output, URLs, paths, and secrets are not shown in bubbles.
---
## Manage your Familiars
Browse installed Familiars, preview their animations, and choose which companion should follow each coding agent from the FamiliarOS desktop app.
<p align="center">
<img src="assets/star-repo.gif" alt="Starring the FamiliarOS repository" width="100%" />
<img src="assets/manage-familiars.png" alt="Managing Familiars in the FamiliarOS desktop app" width="100%" />
</p>
## What is FamiliarOS?
FamiliarOS is a tray-first desktop companion app. A familiar appears on your desktop, keeps you company, and can use bundled abilities for ambient presence, breaks, playful actions, and focus sessions. Coding-agent integrations are still supported as an advanced developer layer.
- **Desktop companion** - a small familiar that idles, reacts, and gives FamiliarOS a friendly presence even before developer tools are configured.
- **Bundled abilities** - first-party plugins can add ambient check-ins, break nudges, playful familiar actions, focus timers, safe little walks, and optional developer notifications.
- **Developer integrations** - advanced setup for Claude Code, OpenCode, Cursor, Pi, and MCP-capable tools when you want coding activity to drive the familiar.
- **MCP ready** - any MCP-capable agent can send short safe speech bubbles and reactions through the FamiliarOS MCP server.
- **Floating chat** - double-click the familiar to open an always-on-top chat window with BYOK OpenAPI-compatible providers, conversation history, and optional MCP Tool Server activation.
- **Virtual-familiar status** - right-click the familiar and open the Virtual Familiar submenu to see hunger, energy, happiness, bond, mood, and level. No on-familiar HUD overlay, so chat clicks stay unobstructed.
- **Single-click petting** - click the familiar once to familiar it; the virtual-familiar bond and happiness increase.
- **Local memory** - the familiar remembers facts, preferences, and notes across sessions.
- **Text-to-Speech (Phase 2)** - configurable system, OpenAI, ElevenLabs, Piper, or OpenAI-compatible TTS for the familiar and floating chat, with voice/model/speed controls and a test preview.
- **Familiar-pack friendly** - loads installed animated familiar packs and can route a selected agent/project to its own familiar window.
- **Privacy-conscious by design** - automatic hook speech is static and local; prompts, code, logs, command output, URLs, paths, and secrets are not shown in bubbles.
## Manage your familiars
Browse installed familiars, preview their animations, and choose which companion should follow each coding agent from the FamiliarOS desktop app.
<p align="center">
<img src="assets/manage-familiars.png" alt="Managing familiars in the FamiliarOS desktop app" width="100%" />
</p>
---
## Quick start
@ -99,14 +141,14 @@ Install the desktop app, then optionally connect your coding agent.
### 1. Install FamiliarOS Desktop
Download the latest app from [FamiliarOS Releases](https://github.com/alvinunreal/familiaros/releases/latest):
Download the latest app from [FamiliarOS Releases](https://github.com/verticaltension/familiaros/releases/latest):
- **macOS Apple Silicon**: `FamiliarOS-*-mac-arm64.dmg`
- **macOS Intel**: `FamiliarOS-*-mac-x64.dmg`
- **Windows**: `FamiliarOS-*-win-x64-setup.exe`
- **Linux**: `FamiliarOS-*-linux-x86_64.AppImage`
Launch FamiliarOS. You should see the desktop familiar and the FamiliarOS tray/menu-bar icon.
Launch FamiliarOS. You should see the desktop Familiar and the FamiliarOS tray/menu-bar icon.
> Current builds may be unsigned. macOS or Windows may show a security warning the first time you open the app.
@ -119,297 +161,42 @@ open /Applications/FamiliarOS.app
### 2. Optional: connect your agent
Use the desktop **Integrations** screen for global setup when available:
FamiliarOS can be driven by Claude Code, OpenCode, Cursor, Pi, or any MCP-capable agent. The desktop app has a central **FamiliarOS MCP Server** panel under **Integrations** where you can choose the command source, override the Node path, pick which Familiar the agent controls, test the server, and copy the MCP JSON.
- **Claude Code** - installs FamiliarOS MCP, Claude memory instructions, and optional Claude hooks.
- **OpenCode** - installs FamiliarOS MCP, an OpenCode instruction file, and the `@familiaros/opencode` plugin.
- **MCP Toolkit** - curated setup guidance for Filesystem, Git, GitHub, Playwright, Browser Use, Memory, Fetch, Docker, and adjacent terminal/system MCP layers.
For detailed setup, see [`docs/claude-integration.md`](docs/claude-integration.md), [`docs/opencode.md`](docs/opencode.md), and [`docs/cursor.md`](docs/cursor.md).
<p align="center">
<img src="assets/integrations.png" alt="FamiliarOS desktop integrations screen" width="100%" />
</p>
---
For project-local setup, run the CLI from the project you want to configure:
## MCP in plain English
```bash
npx -y @familiaros/cli@latest configure --agent claude --familiar <petId>
npx -y @familiaros/cli@latest configure --agent opencode --familiar <petId>
```
FamiliarOS includes three MCP-related surfaces. They are separate on purpose:
If you prefer a permanent `familiaros` shell command, install the CLI once with `npm install -g @familiaros/cli` and replace `npx -y @familiaros/cli@latest` with `familiaros`.
### MCP Tool Servers — tools *for* your Familiar's chat
Project-local setup can create project files such as `.claude/settings.local.json` or `.opencode/opencode.jsonc`. Review them before committing because they may include the selected familiar id.
The **MCP Tool Servers** panel lets the built-in floating chat do real work. Turn on tools such as filesystem, terminal, web fetch, GitHub, SQLite, Docker, or Playwright, then ask your Familiar things like *"List the files in my home directory"* or *"Summarize that PDF in my Knowledge Store."* The tools run inside the desktop app; no external agent is required.
## Advanced: agent integrations
### FamiliarOS MCP Server — your Familiar as a tool *for* external agents
FamiliarOS integrations have three layers:
The **FamiliarOS MCP Server** panel exposes your Familiar to Claude Code, Cursor, OpenCode, Codex CLI, or any other MCP-capable host. Those agents can then make your Familiar react, speak a safe bubble, or read/write memory. This is a small, controlled bridge — external agents do not get unrestricted access to your desktop.
1. **MCP tools** for explicit agent actions.
2. **Agent instructions** so agents know when to use those tools.
3. **Hooks/plugins** for automatic decorative reactions during normal agent work.
### Curated MCP Toolkit — a safe manual for the wider MCP world
### Claude Code
The **Curated MCP Toolkit** is not an automatic installer. It is a curated reference that explains what popular MCP tools do, what permissions they need, and how to set them up manually or as a persistent bundle in supported hosts. It is designed so you can adopt the MCP ecosystem deliberately instead of clicking "install everything."
Claude Code integration supports:
- `familiaros` MCP setup via Claude Code.
- Managed Claude memory instructions in `~/.claude/CLAUDE.md` and `~/.claude/familiaros.md`.
- Managed Claude hooks in `~/.claude/settings.json`.
- Project-local setup through `npx -y @familiaros/cli@latest configure --agent claude --familiar <petId>` or the optional global `familiaros` CLI.
Typical global MCP command shape:
```bash
claude mcp add --scope user familiaros -- npx -y @familiaros/mcp@latest
```
With a selected familiar:
```bash
claude mcp add --scope user familiaros -- npx -y @familiaros/mcp@latest --familiar <petId>
```
See [`docs/claude-integration.md`](docs/claude-integration.md) for the full file layout, hook mapping, project-local behavior, and safety rules.
### OpenCode
OpenCode integration supports:
- An MCP entry using `@familiaros/cli mcp`.
- A managed `familiaros.md` instruction file.
- The `@familiaros/opencode` plugin for automatic reactions.
- Global desktop setup and project-local `.opencode` setup.
Project-local setup:
```bash
npx -y @familiaros/cli@latest configure --agent opencode --familiar <petId>
```
See [`docs/opencode.md`](docs/opencode.md) for global config selection, plugin behavior, project-local setup, and safety rules.
### Generic MCP clients
Any MCP-capable editor or coding agent can talk to FamiliarOS through the MCP server while the desktop app is running.
```json
{
"mcpServers": {
"familiaros": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@familiaros/mcp@latest"]
}
}
}
```
To target a specific installed non-default familiar:
```json
{
"mcpServers": {
"familiaros": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@familiaros/mcp@latest", "--familiar", "<petId>"]
}
}
}
```
Available MCP tools:
- `familiaros_status` - check whether FamiliarOS is reachable and which familiar is targeted.
- `familiaros_react` - set a short reaction on the target familiar.
- `familiaros_say` - show a short safe speech bubble, optionally with a reaction.
- `familiaros_memory_list` - list recent long-term memories stored by FamiliarOS.
- `familiaros_memory_search` - search familiar memory for relevant facts, preferences, or notes.
- `familiaros_memory_store` - store a durable memory for the familiar.
- `familiaros_memory_forget` - delete a stored memory by id.
`familiaros_say` messages must be short, single-line, and must not look like code, logs, secrets, URLs, or file paths.
### MCP Tool Servers
The desktop app includes a dedicated **MCP Tool Servers** panel under **Integrations** for the built-in floating chat. Activate tool servers such as filesystem, terminal, memory, fetch-web, sequential-thinking, playwright, git, github, docker, and sqlite so the familiar can use them directly. This works independently of whether Claude, Cursor, OpenCode, or Pi are installed.
### FamiliarOS MCP Server
A central **FamiliarOS MCP Server** panel under **Integrations** configures the external-agent bridge. It collects command mode (published / bundled / local), node path, and familiar routing in one place, and provides a **Test Server** check and a **Copy MCP JSON** button for pasting into Claude Code, Cursor, Codex CLI, or any other MCP host.
### Curated MCP toolkit
The desktop app also includes a manual-but-curated **Curated MCP Toolkit** panel under **Integrations**. It is there to help you build a practical broader stack without stuffing FamiliarOS full of unsafe one-click third-party installs.
The toolkit offers two paths:
- `Manual Setup` - per-tool guidance, docs links, and copyable snippets
- `Persistent Full Access` - `Install Now` for the supported persistent baseline in hosts such as Claude Code or Codex CLI, plus a matching copyable bundle
The current supported `Install Now` baseline covers:
- Filesystem
- Playwright
- Memory
- Context7 / Docs
- Fetch / Web when `uvx` is available
- Sequential Thinking
- Browser Use when `uvx` is available, with its own runtime credential still required
The current recommended starter set is:
- Filesystem
- Git
- GitHub
- Playwright
- Browser Use
- SQLite / PostgreSQL
- Memory
- Fetch / Web
- Sequential Thinking
- Docker MCP Toolkit
It also maps the next terminal-oriented layers that usually matter once your workflow grows up a bit:
- Shell / Terminal
- Process & Logs
- System Info
- SSH
- Package Manager
- Tmux
- Kubernetes / Cloud
- CI / CD
- Ghidra
- Binary Analysis
- Network Analysis
## How it works
```text
Claude Code / OpenCode / Pi / MCP client
-> @familiaros/mcp, @familiaros/cli mcp, @familiaros/claude hook, @familiaros/opencode plugin, or @familiaros/pi extension
-> @familiaros/client
-> FamiliarOS desktop local IPC discovery file
-> FamiliarOS desktop IPC socket/pipe
-> default familiar or selected agent familiar window
```
The desktop app writes a local discovery file containing an IPC endpoint and a per-run token. Clients must send that token with every request.
For Windows desktop + WSL agent setups, see [`docs/wsl-ipc.md`](docs/wsl-ipc.md) for the opt-in TCP transport.
When an integration is configured with `--familiar <petId>`, FamiliarOS asks the desktop app for a short-lived lease. Valid installed non-default familiars open as explicit agent familiar windows. Missing, invalid, broken, built-in, or default familiar requests fall back to the desktop default familiar.
## Reactions and speech
Automatic hooks are decorative and best-effort. They do not approve, deny, block, or change agent behavior.
Common reaction mapping:
| Agent activity | Reaction |
| --- | --- |
| Prompt/chat starts | `thinking` |
| File edit/write/patch | `editing` |
| Test-like shell command | `testing` |
| Permission request | `waiting` |
| Successful idle/stop | `success` |
| Session/error stop | `error` |
Generic shell activity is intentionally quiet by default. Hook/plugin speech is throttled and selected from local static message pools such as `Approval needed` or `Something failed`.
### Pi extension package
FamiliarOS includes an experimental Pi extension package at `@familiaros/pi`. Pi support is extension-first rather than MCP-first: the extension listens to Pi lifecycle/tool events and sends local best-effort reactions through `@familiaros/client`.
```bash
pi install npm:@familiaros/pi
pi install -l npm:@familiaros/pi
```
Inside Pi, the extension registers `/familiaros status`, `/familiaros test`, `/familiaros react <reaction>`, and `/familiaros say <message>`. Automatic events do not forward prompts, assistant text, tool output, file contents, paths, URLs, or secrets. Real Pi CLI install validation is still required before marking the integration fully supported.
---
## Development
### Requirements
- Node.js 20+
- pnpm 11+
- TypeScript
No Bun runtime is required for development.
### Install
```bash
pnpm install
pnpm --filter @familiaros/desktop build
pnpm --filter @familiaros/desktop test
```
### Run the desktop app
See `FEATURES.md` and `FEATURE_REGISTRY.md` for a full capability map.
```bash
pnpm dev:desktop
```
---
Equivalent package command:
## License
```bash
pnpm --filter @familiaros/desktop dev
```
### Checks
```bash
pnpm check
pnpm typecheck
pnpm build
pnpm test
```
FamiliarOS currently uses lightweight Node contract checks instead of a full test framework. See [`docs/testing.md`](docs/testing.md).
### Package desktop builds
```bash
pnpm package:desktop:dir
pnpm package:desktop
```
Release process details live in [`docs/release.md`](docs/release.md).
## Workspace layout
```text
apps/desktop Electron desktop app
packages/client @familiaros/client, local IPC client
packages/mcp @familiaros/mcp, MCP stdio server
packages/claude @familiaros/claude, Claude command and hook helpers
packages/opencode @familiaros/opencode, OpenCode config and plugin integration
packages/pi @familiaros/pi, Pi extension package
packages/agent-events Shared safe agent event speech helpers
packages/cli @familiaros/cli, user-run CLI, plugin scaffolder/validator, MCP/hook entrypoints
packages/sdk @familiaros/plugin-sdk, plugin SDK v3 types + testing harness
packages/familiar-format @familiaros/familiar-format, familiar/catalog format types
plugins/official First-party plugin source (bundled + catalog)
docs/ Documentation
```
## Documentation
- [`docs/plugins.md`](docs/plugins.md) - plugin platform (SDK v3): manifest, permissions, dev workflow, test kit.
- [`docs/superplugins.md`](docs/superplugins.md) - SDK v3 design rationale and feature spec.
- [`docs/claude-integration.md`](docs/claude-integration.md) - Claude Code setup, MCP, memory, hooks, and safety.
- [`docs/opencode.md`](docs/opencode.md) - OpenCode global/project setup, plugin behavior, and safety.
- [`docs/wsl-ipc.md`](docs/wsl-ipc.md) - Windows desktop + WSL MCP transport setup.
- [`docs/testing.md`](docs/testing.md) - test/check strategy.
- [`docs/release.md`](docs/release.md) - desktop release process.
- [`docs/workflow.md`](docs/workflow.md) - project workflow notes.
## Safety and privacy notes
- FamiliarOS local IPC is local-only and protected by a per-run token.
- Hook/plugin errors are swallowed unless debug logging is enabled.
- Automatic speech is static and local; it does not include model-generated prompt text.
- Tool inputs and command text are used only for coarse reaction classification.
- Managed setup preserves unrelated user config and removes only FamiliarOS-managed entries.
- Speech validation rejects code-like, secret-like, URL-like, path-like, or multiline messages.
MIT

38
README_OUR_CHANGES.md
View file

@ -33,23 +33,32 @@ Store files and add manual knowledge entries that the assistant can reference du
- Relevant files are injected into the assistant's system instructions automatically.
- Combined search across stored files and FamiliarOS memories.
## New: MCP Tool Servers (Built-in Chat)
## New: MCP Tool Servers — Tools for Your Familiar's Chat
Activate MCP tool servers for the built-in floating chat, independently of external agents.
The **MCP Tool Servers** panel gives the built-in floating chat the ability to do real work on your local machine. It is separate from the external-agent bridge.
- Filesystem, Terminal, Memory, Fetch/Web, Sequential Thinking, Playwright, Git, GitHub, Docker, SQLite.
- Top-level **MCP Tool Servers** panel in Control Center → Integrations.
- Tiered browser: Starter, Terminal & Systems, Advanced.
- Tools run through an internal stdio MCP client in the main process.
- Activate tools such as filesystem, terminal, web fetch, sequential thinking, Playwright, Git, GitHub, Docker, and SQLite.
- The tools run through an internal stdio MCP client in the main process.
- Once enabled, you can ask your Familiar things like *"List the files in my home directory,"* *"Summarize that PDF,"* or *"Run this test script."*
- Tools can be turned on or off individually, so you only grant the access you actually want.
## New: FamiliarOS MCP Server Panel
## New: FamiliarOS MCP Server Panel — Your Familiar as a Tool for External Agents
A central panel in Control Center → Integrations configures the external-agent bridge.
The **FamiliarOS MCP Server** panel exposes your Familiar to Claude Code, Cursor, OpenCode, Codex CLI, or any other MCP-capable host.
- Command mode selector (published / bundled / local) in one place.
- Node path override and familiar routing in one place.
- Node path override and Familiar routing in one place.
- One-click **Test Server** health check.
- One-click **Copy MCP JSON** for Claude Code, Cursor, Codex CLI, or generic MCP hosts.
- One-click **Copy MCP JSON** for pasting into your agent's MCP configuration.
- This is a small, controlled bridge: external agents can make your Familiar react, speak a safe bubble, or read/write memory, but they do not get unrestricted access to your desktop.
## New: Curated MCP Toolkit — A Safe Manual for the Wider MCP World
The **Curated MCP Toolkit** is a permission-aware reference surface for adopting the broader MCP ecosystem deliberately.
- It is **not** an automatic installer; it explains what popular MCP tools do, what permissions they need, and how to set them up manually.
- Each entry includes copy-paste snippets and guidance for supported hosts.
- Use it to build a persistent tool bundle or to understand a tool before you enable it.
## New: Familiar Scale
@ -64,9 +73,16 @@ A central panel in Control Center → Integrations configures the external-agent
## New: Familiar Character & Base Instructions
- Give your familiar a custom system-prompt style character in Settings.
- Give your Familiar a custom system-prompt style character in Settings.
- Toggle whether the default FamiliarOS behavior instructions are included in every chat.
## New: Custom Familiar Name
- Name your default Familiar in Settings → General.
- The chosen name appears in the tray tooltip, tray context menu, and anywhere the default Familiar is referenced.
- If no name is set, the menu falls back to the Familiar's display name or "Built-in Familiar."
## New: Text-to-Speech (Phase 2)
The familiar can now speak aloud using a configurable TTS provider.

0
packages/install-familiar/src/check-install-pet.ts → packages/install-familiar/src/check-install-familiar.ts
View file