Content
# Claude Familiar
<p align="center">
<img src="assets/banner.png" alt="Claude Familiar" />
</p>
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](https://bun.sh) v1.0+
- [jq](https://jqlang.github.io/jq/) (used by MCP tool scripts to parse JSON — `brew install jq`)
- Claude Code with plugin support
### 1. Clone and install
```bash
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
```bash
# 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
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.
```bash
# 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:
```json
{
"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](https://github.com/yaniv-golan/mcp-bash-framework) — 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](https://github.com/yaniv-golan/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](https://github.com/yaniv-golan/claude-code-internals) during skill development.
## License
MIT
