claude-familiar

Give your Claude Code companion a personality, mood, backstory, and interactive commands — or build your own companion plugin that stacks with others.
What you get
Out of the box, the Claude Code companion reacts with generic messages that can't be customized by plugins. With Claude Familiar installed:
- **Personality and traits** are injected into every session — the companion responds in character
- **Mood** shifts automatically as you work (cheerful after successes, grumpy after failures) and decays over time
- **Lore** accumulates across sessions — add backstory entries that persist
- **Interactive commands** — ask for fortunes, code roasts, haiku, stats, and more
- **Extensible** — other plugins can add their own traits, lore, and mood modifiers by declaring "x-familiarExtensions" in their plugin.json. Everything merges automatically.
With the optional binary patch
The companion's speech bubble normally calls Anthropic's reaction API. The patch redirects it to a local server (familiar-react) that reads your familiar's state, calls Claude Haiku in-character, and sends the reaction to the bubble. Without the patch, commands like fortune and roast still work — they just appear in Claude's response text instead of the speech bubble.
> **Warning:** familiar-patch modifies the Claude Code binary. It replaces a single function (695 bytes) with one that calls http://127.0.0.1:19542/react instead. The full patch logic is in packages/familiar-patch/src/patcher.ts — read it before you run it. A backup is created before patching and can be restored at any time. The patch must be re-applied after Claude Code auto-updates. This is not supported or endorsed by Anthropic.
---
Quick start
Prerequisites
- Bun v1.0+
- jq (used by MCP tool scripts to parse JSON — brew install jq)
- Claude Code with plugin support
1. Clone and install
> **Note:** The SDK, reaction server, and patcher are bundled into the plugin automatically. After installing, the monorepo checkout is only needed for development.
2. Install the plugin
On session start, the plugin runs familiar-sdk init, starts familiar-react, and pre-authorizes MCP tools **when the SDK can be resolved** (state file sdkPath, FAMILIAR_SDK_PATH, or monorepo sibling). If resolution fails, the SessionStart hook returns empty output and no state is created — run init manually (below).
If you need to initialize manually (recommended before the first session if the hook might not find the repo), run from anywhere:
3. Apply the binary patch (optional)
Without the patch, everything works — commands just respond in chat text instead of the companion bubble.
If check returns unknown, your Claude Code version isn't supported yet — open an issue. Currently supported: **v2.1.89**, **v2.1.91**, **v2.1.92**.
Exit codes for patch check: **0** = patched, **1** = unpatched, **2** = unknown.
After Claude Code auto-updates, re-apply the patch with the same apply command.
**familiar-react** (dev / manual runs): bun run packages/familiar-react/bin/familiar-react.ts supports **restart** and **stop** subcommands (see Contributing).
---
Using your familiar
In any Claude Code session — either type naturally or use the /familiar slash command:
| Say / type... | What happens |
|---|---|
| "tell me a fortune" | Delivers a fortune (via bubble if patched, inline if not) |