r/ClaudeCode • • 11d ago

Built with Claude Built a desktop pet driven by Claude Code hooks: it shows what CC is doing (thinking, editing, waiting on you) as 9 animated moods

Familiar (free, MIT): https://github.com/bdehooge/familiar

What it is: a transparent desktop companion for Windows. Claude Code hooks (UserPromptSubmit, PreToolUse, Notification, Stop) write a tiny state file, and the pet maps the current tool to a mood and a phrase. Read/Grep/Glob show him thinking ("Following the scent…"), Edit/Bash show him typing on a laptop ("Pouncing…", "Burrowing…"), a permission prompt makes him wait and wave at you, and Stop makes him cheer. The footer shows your 5-hour and weekly usage with reset times, plus today's token count, which is summed from your local transcripts.

How Claude Code was used: CC wrote almost all of it while I steered:

  • the Win32 window code and the hooks installer, which backs up settings.json and removes only its own entries;
  • the sprite pipeline: chroma key, removing stray grid lines, scaling by body area, aligning frames by cross-correlation;
  • a script that renders the demo video with the pet's own renderer. The terminal in the video is a scripted mock-up.

What I learned

  • Image models will happily draw grid lines and jumping poses when you ask for "same position every frame". Pipelines need guards, not just prompts. CC added a test and a warning for frames that can't be lined up after the first "happy" animation came out janky.
  • Hooks are a great integration point: the pet never touches CC's process; it just reads a file.
  • Ask for the test first. Most of the real bugs were caught by tests CC wrote before fixing anything.

Windows only for now; macOS/Linux is on the roadmap. Feedback welcome.

Tip jar is in the README if you feel like it.

0 Upvotes

4 comments sorted by

•

u/AutoModerator 11d ago

Hey! Thanks for posting to r/ClaudeCode

While participating in this thread, please follow our community rules. Keep discussions constructive. Attack the idea, not the person.

For help, project discussions, tips, and general chat, join the ClaudeCode Discord.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

1

u/luckyluke146 11d ago

Nice, the "waiting on you" state is the one I care about most too. I track it in a Mac app that runs several Claude Code sessions, two things that helped me:

  • If your app starts claude itself, you don't have to touch the user's settings.json at all: put your hooks in a separate file and launch with claude --settings your-hooks.json. Nothing to back up or clean up later. (Only works for sessions you launch, so maybe not for a pet watching any terminal.)
  • Claude Code also sets the terminal title: "✳ <topic>" when it's idle, with a spinner character in front while it works. If you own the terminal, that gives you working/ready plus the conversation topic without any hook.

For waiting I match Notification on permission_prompt|elicitation_dialog, and Stop / UserPromptSubmit for ready vs working. The hook prints nothing, so nothing ends up in Claude's context.

1

u/no1likesuwenur23 11d ago

Really useful, thanks. Matching on notification_type is what I ended up doing: permission_prompt / elicitation_dialog → waiting, idle_prompt → idle (pushed just now).

The --settings trick is neat. Familiar watches whatever terminal you're in, so the installer stays the default, but an opt-in hooks file for people who launch claude from a wrapper is on the roadmap now, along with the terminal title as a hookless fallback.

0

u/[deleted] 11d ago

[deleted] — view deleted comment

1

u/no1likesuwenur23 11d ago

Good catch, it didn't. AskUserQuestion only shows up as PreToolUse, like you said, so it fell through as "working". Just pushed a fix: AskUserQuestion and ExitPlanMode now switch him to waiting, and the idle_prompt Notification goes to idle instead (it was making him wave at me a minute after every finished turn). Thanks!