claude-familiar

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

git clone https://github.com/yaniv-golan/claude-familiar.git
cd claude-familiar
bun 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

# Register this repo as a local marketplace source
claude plugin marketplace add /path/to/claude-familiar

# Install the plugin
claude plugin install familiar-extras@claude-familiar

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:

bash /path/to/claude-familiar/familiar.sh init

3. Apply the binary patch (optional)

Without the patch, everything works — commands just respond in chat text instead of the companion bubble.

# Check current status
bash /path/to/claude-familiar/familiar.sh patch check

# Apply (creates backup automatically)
bash /path/to/claude-familiar/familiar.sh patch apply

# Restore original binary at any time
bash /path/to/claude-familiar/familiar.sh patch restore

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: