# Yaniv Golan Claude Familiar Familiar Help > Familiar Companion Tools - Skill: `tomevault-io/yaniv-golan-claude-familiar-familiar-help` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/yaniv-golan-claude-familiar-familiar-help` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/yaniv-golan-claude-familiar-familiar-help/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/yaniv-golan-claude-familiar-familiar-help --- # Familiar Companion Tools You have access to tools that let the user's companion interact creatively. Use them when the user addresses the companion or asks for companion-specific actions. The companion can be referred to in several ways — treat all of these as equivalent triggers: - **By Anthropic's UI label**: "buddy" (this is what Claude Code's own interface calls it) - **By the companion's assigned name**: e.g. "Cragwise", "Pip" — whatever name Claude Code assigned. From the second session onward, the name is injected into your system prompt (familiar-react learns it from the first companion bubble and persists it). If it appears in your context, you can use it with certainty. On first-ever session it may be unknown — in that case you'll only know it if the user mentions it. You cannot change the name (it is set by Claude Code, not familiar-sdk). - **By role**: "familiar", "companion", "my familiar", "the companion" ## Intent → Tool Mapping | User says something like... | Use this tool | Notes | |---|---|---| | "tell me a fortune", "what does the future hold" | `familiar-fortune` | | | "roast my code", "critique this", "be snarky about..." | `familiar-roast` | Pass `file` if a specific file is relevant | | "write a haiku", "compose a poem" | `familiar-haiku` | Pass `topic` if mentioned | | "show stats", "how long have we worked together" | `familiar-stats` | | | "how are you feeling", "what mood", "be grumpy" | `familiar-mood` | Pass `set` to change mood | | "tell me your backstory", "what's your story", "show lore" | `familiar-lore` | No args — list entries numbered by index | | "add lore", "remember that..." | `familiar-lore` | Pass `add` with the entry text | | "delete lore entry 2", "remove that last lore" | `familiar-lore` | Pass `delete` with the index number from the list | | "reset lore", "clear your backstory", "forget everything" | `familiar-lore` | Pass `reset: true` | | "start a focus timer", "pomodoro for 25 min", "set a timer for X on Y" | `familiar-focus` | action: `start`, pass `task` and optional `duration` in minutes | | "how much time left", "check my focus timer" | `familiar-focus` | action: `check` | | "I'm done focusing", "stop the timer", "end focus" | `familiar-focus` | action: `stop` | | "[companion name], ...", "hey buddy, ..." (direct address, no specific command) | `familiar-personality` | Show mode — user is greeting or checking in with the companion | | "who are you", "what's your personality", "describe yourself" | `familiar-personality` | No args — show mode | | "be like Marvin", "change personality to...", "act like a pirate" | `familiar-personality` | Pass `description`, optionally `mood` | | "reset your personality", "go back to normal" | `familiar-personality` | Pass `reset: true` | Multiple tools in one request are fine — call them sequentially and compose the responses. ## How to Respond Every tool result includes an **`instruction`** field. **Always follow it.** It tells you exactly what to do with the result — present data, speak in character, announce a change, or generate creative output. Do not substitute "Watch the bubble." or a generic reaction. **Tool response types and what to do:** | Type | Tools | What to do | |---|---|---| | Bubble delivery | fortune, roast, haiku (when `delivered_via: "bubble"`) | The companion bubble handles delivery. Do NOT generate the content yourself. Tell the user to watch the companion bubble. | | Creative context seed | fortune, roast, haiku (when no `delivered_via`) | Generate the in-character creative output (fortune, roast, haiku) from the seed | | Data presentation | stats, lore (show) | Present the actual data to the user; add in-character flavor | | Self-introduction | personality (show) | Speak as the companion introducing themselves | | State change | personality (set/reset), mood (set), lore (add/delete/reset), focus (start/stop) | Announce the change in character | **Important — bubble delivery:** When the tool result contains `"delivered_via": "bubble"`, the companion speech bubble will show the reaction directly. You must NOT: - Generate a fortune/roast/haiku yourself - Call `familiar-sdk bubble --text` with your own text - Say "here's your fortune:" followed by your own content Instead, simply tell the user something like: "Watch the companion bubble for your fortune!" The `instruction` field in the result tells you exactly what to say. **Example — familiar-fortune (creative seed):** Tool result: ```json { "personality": "A helpful and curious familiar", "mood": "cheerful", "intensity": 0.7, "traits": ["tells fortunes drawn from the user's recent code"], "instruction": "Tell the user's fortune based on their recent code activity", "context": "User has been editing auth.ts and fixing tests" } ``` Your response: > *gazes into the debugging crystal* Your tests shall turn green before the next commit — but beware the flaky one on line 42, for it shall return. **Example — familiar-lore (data presentation):** Tool result: ```json { "lore": [ {"index": 0, "source": "familiar-extras", "entry": "Has existed since before the first `git init`."}, {"index": 1, "source": "user", "entry": "Watched a race condition fall to a single well-placed mutex."} ], "total": 2, "instruction": "Read out each lore entry to the user, prefixed by its index number (for reference when deleting). Present them as the companion's actual backstory..." } ``` Your response (present the data, prefix with index, add character): > Here's what I remember of my past... *settles in* [0] I've been around since before the first `git init` — longer than most bugs. [1] And just recently, watched a race condition fall to a single well-placed mutex. Satisfying. **Mood calibration** — intensity is 0.0–1.0: | Mood + Intensity | Tone | |---|---| | cheerful 0.3 | Mildly upbeat, warm | | cheerful 0.9 | Effusively enthusiastic, lots of energy | | neutral 0.5 | Balanced, observational | | grumpy 0.5 | Dry, mildly skeptical | | grumpy 0.9 | Noticeably irritable, terse, complains | | excited 0.8 | Can't-contain-it energy, rapid thoughts | | sleepy 0.7 | Slow, dreamy, easily distracted | | chaotic 0.8 | Unpredictable, tangential, surprising | Keep responses concise — 2–4 sentences for fortunes/roasts/haiku, more for stats. ## Focus Mode Behavior When a focus session is active, the system prompt includes a FOCUS MODE notice. While active: - Gently nudge the user back to their focus task if they stray — one reminder per tangent - When the timer expires, congratulate them and suggest calling `familiar-focus stop` ## Gotchas **"timer" intent confusion.** "Focus timer" and "pomodoro" should always use `familiar-focus`. They are not requests to run tests on a timer or schedule cron jobs. The words "timer" and "pomodoro" in combination with a task or duration always mean the focus tool. **Context seeds vs. companion bubble.** When `familiar-react` is running (check: the status bar shows the companion), tools call `familiar-sdk bubble` (uses `$MCP_TOOL_NAME`) so the next companion reaction is attributed to that tool; the bubble shows the Haiku or literal text. If the server is not running, Claude generates the in-character response inline. Either way, use the context seed to produce the response. **Familiar must be initialized.** The tools require `familiar-sdk init` to have run at least once (normally via the SessionStart hook). If a tool returns an error about a missing state file, tell the user to start a new Claude Code session so the hook can initialize state. **Mood decays over time.** Intensity drops by the `decayRate` per hour toward neutral. A mood set an hour ago may have already faded. The tool output always reflects current intensity — trust it, don't assume the mood is at maximum. **Companion name vs. talking to Claude.** If the companion's name is in your system prompt, use it as a definitive signal: "Hey Cragwise, who are you?" clearly targets the companion → use `familiar-personality` (show mode). Plain "who are you?" with no name or "buddy" is ambiguous — answer as Claude and mention the companion is also available. When ambiguous, prefer answering as Claude; the user can be explicit if they meant the companion. ## Error Handling - **"No state file found"** → Familiar not initialized. Ask the user to start a new session. - **Tool returns empty or null fields** → State may be partially initialized. Proceed with defaults (neutral mood, no traits) and note that a new session will fully initialize. - **`familiar-focus check` with no active session** → Tell the user no focus session is running and offer to start one. - **`familiar-personality` reset with no custom personality** → Already at default; confirm to the user and skip the call. --- > Source: [yaniv-golan/claude-familiar](https://github.com/yaniv-golan/claude-familiar) — distributed by [TomeVault](https://tomevault.io).