diff --git a/FEATURES.md b/FEATURES.md index c28d376b..e3e3917c 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -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 diff --git a/FEATURES_OUR_CHANGES.md b/FEATURES_OUR_CHANGES.md index 48625158..d62044f1 100644 --- a/FEATURES_OUR_CHANGES.md +++ b/FEATURES_OUR_CHANGES.md @@ -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 diff --git a/FEATURE_REGISTRY.md b/FEATURE_REGISTRY.md index 2bfa991f..4b53bbef 100644 --- a/FEATURE_REGISTRY.md +++ b/FEATURE_REGISTRY.md @@ -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 diff --git a/PULL_REQUEST.md b/PULL_REQUEST.md index 8bd62373..e58bdd29 100644 --- a/PULL_REQUEST.md +++ b/PULL_REQUEST.md @@ -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 diff --git a/README.md b/README.md index e24708ad..bc7edabc 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,21 @@

- FamiliarOS - pixel art desktop companion + FamiliarOS

- A tiny desktop companion that keeps you company. + Your AI Companion That Lives With You.

- 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. FamiliarOS lives on your desktop.

- This branch also includes a floating chat surface, local memory, Knowledge Store, MCP Tool Servers, an FamiliarOS MCP Server panel, a Curated MCP Toolkit, Text-to-Speech (Phase 2), and expanded familiar sizing. See FEATURES.md, FEATURE_REGISTRY.md, and PULL_REQUEST.md for details. + At its heart is your Familiar: 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. +

+ +

+ This fork includes a floating chat surface, local memory, Knowledge Store, MCP Tool Servers, a FamiliarOS MCP Server panel, a Curated MCP Toolkit, Text-to-Speech, Familiar naming, and expanded familiar sizing. See FEATURES.md, FEATURE_REGISTRY.md, and PULL_REQUEST.md for details.

@@ -27,18 +31,37 @@

+--- +## 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.

- Starring the FamiliarOS repository + Managing Familiars in the FamiliarOS desktop app

-## 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. - -

- Managing familiars in the FamiliarOS desktop app -

+--- ## 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). -

- FamiliarOS desktop integrations screen -

+--- -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 -npx -y @familiaros/cli@latest configure --agent opencode --familiar -``` +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 ` 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 -``` - -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 -``` - -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", ""] - } - } -} -``` - -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 `, 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 `, and `/familiaros say `. 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 diff --git a/README_OUR_CHANGES.md b/README_OUR_CHANGES.md index 556820aa..903a9638 100644 --- a/README_OUR_CHANGES.md +++ b/README_OUR_CHANGES.md @@ -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. diff --git a/packages/install-familiar/src/check-install-pet.ts b/packages/install-familiar/src/check-install-familiar.ts similarity index 100% rename from packages/install-familiar/src/check-install-pet.ts rename to packages/install-familiar/src/check-install-familiar.ts