FamiliarOS

Create your Familiar.

Your Familiar remembers, speaks, and acts across your system.

A local-first AI companion with memory, voice, knowledge, and tools.

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

FamiliarOS reacting across multiple coding agent sessions

by Boring Dystopia Development

boringdystopia.ai  X @alvinunreal  Telegram Join channel 

--- ## 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. > **Not just an assistant. A Familiar.** 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/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 verticaltension/familiaros --skill familiaros ``` Then open Claude Code, OpenCode, Codex, or another skill-aware agent and say: ```text Use the FamiliarOS skill. Install FamiliarOS for me, connect this agent, and verify the integration works. ``` 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. ``` 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. Debug why familiaros_status is unavailable. ``` --- ## 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. - **MCP Toolkit Guide** — a hand-picked guide to popular MCP tools: what each does, what permissions it needs, and how to add it yourself. Nothing installs automatically. - **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.

Managing Familiars in the FamiliarOS desktop app

--- ## Quick start Install the desktop app, then optionally connect your coding agent. ### 1. Install FamiliarOS Desktop 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. > Current builds may be unsigned. macOS or Windows may show a security warning the first time you open the app. If macOS says the app is damaged or should be moved to Trash, remove the quarantine flag and open it again: ```bash xattr -dr com.apple.quarantine /Applications/FamiliarOS.app open /Applications/FamiliarOS.app ``` ### 2. Optional: connect your agent 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. 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). --- ## MCP in plain English FamiliarOS includes three MCP-related surfaces. They are separate on purpose: ### MCP Tool Servers — tools *for* your Familiar's chat 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. ### FamiliarOS MCP Server — your Familiar as a tool *for* external agents 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. ### MCP Toolkit Guide — a safe manual for the wider MCP world The **MCP Toolkit Guide** is not an automatic installer. It is a hand-picked 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." --- ## Development ```bash pnpm install pnpm --filter @familiaros/desktop build pnpm --filter @familiaros/desktop test ``` See `FEATURES.md` and `FEATURE_REGISTRY.md` for a full capability map. --- ## License MIT