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

_{by Boring Dystopia Development}

     

---

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

npx skills add verticaltension/familiaros --skill familiaros

Then open Claude Code, OpenCode, Codex, or another skill-aware agent and say:

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:

Use the FamiliarOS skill. Help me choose or install a Familiar, configure it for this project, and verify the project integration.

Useful prompts:

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.

---

Quick start

Install the desktop app, then optionally connect your coding agent.

1. Install FamiliarOS Desktop

Download the latest app from FamiliarOS Releases:

• 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:

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/opencode.md, and 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

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