openpetswithchatandmcp/README.md

<p align="center">
  <img src="assets/familiaros.png" alt="FamiliarOS" width="100%" />
</p>

<p align="center">
  <strong>Create your Familiar.</strong>
</p>

<p align="center">
  Your Familiar remembers, speaks, and acts across your system.
</p>

<p align="center">
  <sub>A local-first AI companion with memory, voice, knowledge, and tools.</sub>
</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, an <strong>MCP Toolkit Guide</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">
  <img src="assets/intro.png" alt="FamiliarOS reacting across multiple coding agent sessions" width="100%" />
</p>

<div align="center">
  <p><sub>by <b>Boring Dystopia Development</b></sub></p>
  <p>
    <a href="https://boringdystopia.ai/"><img src="https://img.shields.io/badge/boringdystopia.ai-111111?style=for-the-badge&logo=vercel&logoColor=white" alt="boringdystopia.ai"></a>&nbsp;
    <a href="https://x.com/alvinunreal"><img src="https://img.shields.io/badge/X-@alvinunreal-000000?style=for-the-badge&logo=x&logoColor=white" alt="X @alvinunreal"></a>&nbsp;
    <a href="https://t.me/boringdystopiadevelopment"><img src="https://img.shields.io/badge/Telegram-Join%20channel-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white" alt="Telegram Join channel"></a>&nbsp;
  </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.

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

<p align="center">
  <img src="assets/manage-familiars.png" alt="Managing Familiars in the FamiliarOS desktop app" width="100%" />
</p>

---

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