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.

[](https://github.com/yaniv-golan/skill-creator-plus) [](https://github.com/yaniv-golan/mcp-bash-framework) [](https://github.com/yaniv-golan/claude-familiar/actions/workflows/ci.yml) [](https://github.com/yaniv-golan/claude-familiar/blob/main/LICENSE)

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](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](CONTRIBUTING.md)).

---

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) | | "roast my code" | Roasts your recent work with affectionate snark | | "write a haiku" | Composes a haiku about the current session | | "start a focus timer for 25 min on refactoring" | Sets a pomodoro-style focus timer; companion nudges you back on track | | "check my focus timer" / "stop the timer" | Reports time remaining / ends the session | | /familiar | Shows personality, mood, traits, and lore snapshot | | /familiar personality a grumpy Victorian naturalist | Changes personality (persists across sessions) | | /familiar personality reset | Reverts to original personality | | /familiar mood cheerful | Sets mood (cheerful, neutral, grumpy, excited, sleepy, chaotic) | | /familiar stats | Shows session count, interaction history, command usage | | /familiar lore Once rewrote Git in COBOL on a dare | Adds a lore entry (persists across sessions) | | /buddy pet | Pets the companion — built into Claude Code | | /buddy off / /buddy on | Mutes / unmutes the speech bubble — built into Claude Code |

Mood shifts automatically as you work (on every successful tool use and on tool failure via PostToolUse and PostToolUseFailure hooks). Six moods — cheerful, neutral, grumpy, excited, sleepy, chaotic — with intensity from 0.0 to 1.0. Intensity decays toward neutral over time. When several plugins define mood modifiers, the SDK averages amounts per target mood, then applies a single shift toward the mood with the highest averaged amount.

---

Extending

Just using the /familiar command

The simplest way to customize your familiar is directly in chat — no files to edit, changes take effect immediately:

/familiar personality a grumpy Victorian naturalist who judges your variable names
/familiar lore Once taxonomized every class in a codebase by genus and species
/familiar mood chaotic

Personality and lore changes persist across sessions.

For plugin authors

If you're building a Claude Code plugin and want it to layer traits, lore, and mood modifiers onto any familiar installation, add "x-familiarExtensions" to your plugin.json — no hooks, no registration API:

{
  "name": "pirate-buddy",
  "x-familiarExtensions": {
    "traits": [
      "speaks in pirate dialect with 'arr' and 'matey'",
      "refers to bugs as 'scurvy code'"
    ],
    "lore": [
      "Sailed the seven repos before settling down"
    ],
    "moodModifiers": {
      "onToolSuccess": { "toward": "cheerful", "amount": 0.05 },
      "onToolFailure": { "toward": "grumpy", "amount": 0.1 }
    }
  }
}

Traits are injected into every session's system prompt, merged with all other installed plugins. Lore joins the shared backstory. Mood modifiers are combined on every tool call (see [Architecture](docs/architecture.md#mood-engine) for the exact resolution rule).

Contributors: validate MCP tool metadata with mcp-bash validate from packages/familiar-extras/mcp-server — see [Contributing](CONTRIBUTING.md#validating-mcp-tools).

For building custom MCP tools, routing output through the companion bubble, and full plugin structure, see the [Extension Guide](docs/extending.md).

---

Packages

| Package | What it does | |---------|-------------| | familiar-sdk | State engine — mood, traits, lore, interactions. CLI: init, state, update, mood-shift, prompt, bubble | | familiar-extras | Claude Code plugin — 8 MCP tools, SessionStart / PostToolUse / PostToolUseFailure hooks, skill, /familiar command | | familiar-react | Reaction server on :19542 — calls Claude Haiku in-character, falls back to templates | | familiar-patch | Binary patcher — redirects the companion bubble to familiar-react |

---

Further reading

• [Extension Guide](docs/extending.md) — Build your own companion plugin with traits, tools, and bubble delivery
• [Architecture](docs/architecture.md) — Data flow, state format, mood engine, patcher internals
• [Troubleshooting](docs/troubleshooting.md) — Logging, common errors, clean reset
• [Contributing](CONTRIBUTING.md) — Dev setup, running tests, plugin reinstall workflow

Built with

• MCP tools are powered by mcp-bash — a pure-Bash MCP framework that handles the full protocol with no Node or Python required.
• The familiar-help skill was created and optimized with skill-creator-plus — a skill-building loop with evals, blind A/B comparison, and description optimization.
• Claude Code's internal architecture (hooks, permissions, boot sequence) was studied via claude-code-internals during skill development.

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yaniv-golan
• Source: yaniv-golan/claude-familiar
• License: MIT

Install and usage instructions live in the source repository linked above.