A tiny desktop companion that keeps you company.

A playful familiar that lives on your desktop, keeps you company, and can grow with bundled abilities and developer integrations.

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

_{by Boring Dystopia Development}

     

---

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 alvinunreal/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.

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.

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.

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

Use the desktop Integrations screen for global setup when available:

• 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 project-local setup, run the CLI from the project you want to configure:

npx -y @familiaros/cli@latest configure --agent claude --familiar <petId>
npx -y @familiaros/cli@latest configure --agent opencode --familiar <petId>

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.

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.

Advanced: agent integrations

FamiliarOS integrations have three layers:

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.

Claude Code

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:

claude mcp add --scope user familiaros -- npx -y @familiaros/mcp@latest

With a selected familiar:

claude mcp add --scope user familiaros -- npx -y @familiaros/mcp@latest --familiar <petId>

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

npx -y @familiaros/cli@latest configure --agent opencode --familiar <petId>

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

{
  "mcpServers": {
    "familiaros": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@familiaros/mcp@latest"]
    }
  }
}

To target a specific installed non-default familiar:

{
  "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

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

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

pnpm install

Run the desktop app

pnpm dev:desktop

Equivalent package command:

pnpm --filter @familiaros/desktop dev

Checks

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.

Package desktop builds

pnpm package:desktop:dir
pnpm package:desktop

Release process details live in docs/release.md.

Workspace layout

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 - plugin platform (SDK v3): manifest, permissions, dev workflow, test kit.
• docs/superplugins.md - SDK v3 design rationale and feature spec.
• docs/claude-integration.md - Claude Code setup, MCP, memory, hooks, and safety.
• docs/opencode.md - OpenCode global/project setup, plugin behavior, and safety.
• docs/wsl-ipc.md - Windows desktop + WSL MCP transport setup.
• docs/testing.md - test/check strategy.
• docs/release.md - desktop release process.
• 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.