A desktop pet that reacts to your world.
简体中文 · English · Download · Documentation · Issues
Familiar is a local-first desktop companion for coding agents. It turns Hook events into the actions, task bubbles, and status changes of a pixel-art desktop pet—without adding another dashboard to watch.
Contents
- Multi-agent support: Claude-code, ChatGpt, DeepSeek Harness... one desktop pet handles them all.
- One less window to watch: Follow agent activity through pet actions and task bubbles.
- Fits your workflow: Connect through agent Hook APIs while preserving existing configuration.
- Your data, your choice: Run locally by default; configure remote connections when needed.
Install the desktop app on macOS:
brew install --cask Monster12138/familiar/familiarInstall the CLI on macOS or Linux:
brew install Monster12138/familiar/familiar-cliDownload the latest release from GitHub Releases.
| Platform | Architecture | Installation |
|---|---|---|
| macOS | arm64 / x86_64 | Homebrew Cask or release download |
| Windows | x86_64 | Release download |
| Linux | x86_64 | .deb / AppImage |
Note
macOS packages are not notarized with an Apple Developer ID, and Windows packages are not code-signed. Gatekeeper or SmartScreen may require manual approval on first launch.
First launch on macOS: allow an unnotarized app
Because Familiar is not yet notarized, macOS blocks it the first time you open it. If you installed Familiar from this repository's Homebrew tap or GitHub Releases, allow it manually:
-
Open Familiar. When macOS says it cannot verify the app, click Done.
-
Open System Settings → Privacy & Security, scroll to Security, find the message that Familiar was blocked, and click Open Anyway.
-
In the confirmation dialog, click Open Anyway again. Authenticate with your password or Touch ID if macOS asks. Familiar will open normally from then on.
Only bypass this warning when you obtained Familiar from the official sources linked above.
- Launch Familiar and choose local mode in onboarding.
- Connect an agent: Preview and confirm Hook injection in onboarding or Settings → Hooks.
- Start an agent task and watch the pet actions and task bubbles respond to its activity.
- Make it yours: Choose visible content, click-through, or fullscreen auto-hide in Settings → Display Configuration, and switch companions in Pet Materials.
Tip
For agents running on another machine, use remote mode and manage Hooks on the server.
- Reactive desktop pet — Pixel-art actions follow agent activity without interrupting your flow.
- Agent integrations — Connect Claude Code, Codex CLI, DeepSeek Harness, Qoder, and Google Antigravity through their Hook APIs.
- Remote connections — Run the Agent and Familiar server remotely while the local desktop client subscribes to pet state.
- System dashboard — Show CPU, memory, and disk usage beside the pet.
- Sprite packs — Import more companions with the
.fpackformat. - Lightweight — Pause unnecessary polling while UI surfaces are hidden.
- Privacy-first — Process events locally by default, with no telemetry and minimal operational logs.
- Fullscreen auto-hide — Optionally hide the pet when the foreground app fills its screen on macOS / Windows, then restore it on exit. Off by default; unavailable on Linux.
| Integration | Transport | Status |
|---|---|---|
| Claude Code | Hooks | Available |
| Codex CLI | Hooks | Available |
| DeepSeek Harness | Hooks | Available |
| Qoder | Hooks | Available |
| Google Antigravity | Hooks | Available |
Familiar only manages its own Hook entries. Installation creates a backup and preserves existing agent configuration.
Local mode remains the default. In remote mode, the Agent and familiar-cli serve run on the same remote machine, while the desktop app subscribes to render-state updates over WebSocket.
Remote mode is not a Hook relay: the desktop client cannot forward local Agent events or modify Hooks on the server. See Remote Deployment for TLS, authentication, and deployment instructions.
Familiar may read recent task descriptions, command text, tool names, file paths, and referenced Antigravity transcripts to render the current state. It does not persist full transcripts or Agent event history, and operational logs exclude raw prompts, commands, paths, and Hook payloads.
Remote mode sends bounded render-state summaries to the configured Familiar server/client connection. It does not expose a remote query API for full prompts, transcripts, file contents, Hook payloads, or command output.
See Privacy & Data Handling for details.
Requirements: Rust 1.88+, Node.js 18+, npm, and the desktop prerequisites for your platform.
# Build the CLI resource required by the desktop app
cargo build --release -p familiar-cli
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cd app
npm ci
npm run build
npm run tauri dev- Privacy & Data Handling
- Remote Deployment
- Design Notes
- Sprite Pack Guide
- Development Workflow
- Release Process
Issues and pull requests are welcome. Please read CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md first.
Keep Familiar privacy-first: do not add telemetry or persist captured prompts, transcripts, file contents, or Hook payloads without an explicit product decision.
Familiar is dual-licensed under MIT or Apache-2.0. Built-in sprites, sprite archives, and application icons use the same project license; see ASSETS.md.