familiar-help

install

source · Clone the upstream repo

git clone https://github.com/yaniv-golan/claude-familiar

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/yaniv-golan/claude-familiar "$T" && mkdir -p ~/.claude/skills && cp -r "$T/packages/familiar-extras/skills/familiar-help" ~/.claude/skills/yaniv-golan-claude-familiar-familiar-help && rm -rf "$T"

manifest: packages/familiar-extras/skills/familiar-help/SKILL.md

source content

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:

{
  "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:

{
  "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.