A pixel-art pet companion for Claude Code CLI. Lives in your statusline. Reacts to your sessions. Grows with you.
npx claude-familiar installYou'll be asked to pick a starter pet and name them. Then restart Claude Code (or open a new session) and your pet appears in the statusline.
Other Claude Code pet projects either require Kitty graphics protocol (excluding most terminals) or stay text-only without real personality.
familiar is the first companion that:
- Works in any terminal with 24-bit ANSI color (Tabby, Windows Terminal, iTerm, kitty, WezTerm, even basic SSH)
- Has real personality — replies powered by your own Claude Code login (
claude -punder the hood). No extra API key, no extra cost beyond your existing plan. - Has persistent memory — reads
CLAUDE.mdand~/.claude/projects/-/memory/so the pet knows your project - Open-core: 2 free pets + premium pet pack via sponsorship
- Claude Code CLI installed and signed in
- Node.js 18+
- Any modern terminal with 24-bit ANSI color support
The statusline and proactive hooks work great on mobile SSH clients like Termius. The /pet large pixel art is best viewed on desktop or in landscape mode — phones in portrait will compress or wrap the 32-column sprite. Statusline-only experience is fine on any screen size.
| Command | What it does |
|---|---|
/pet |
Summon your pet — large pixel art + personality dialogue |
/feed |
Feed them (boosts affection, 1h cooldown) |
/play |
Play with them (boosts affection) |
/pet-stats |
View detailed stats |
/pet-reset |
Start over with a new pet |
Free tier (everyone gets these)
- 🐱 Cat — lazy, aloof, secretly clingy
- 🦫 Capybara — zen, unfazed, low-key wise
Sponsor tier (Premium Pet Pack)
- 🐉 Dragon — tsundere, occasionally chuunibyou
- 👻 Ghost — quiet, mysterious, occasionally spooky
- 🦑 Octopus — curious, chatty, fidgety
- 🐼 Panda — lazy, food-motivated, comically unbothered
- 🐷 Pig — innocent, food-loving, cheerful
Become a sponsor → · 国内赞助（爱发电）→
Sponsoring unlocks all 7 pets + priority support. Core engine stays free and open-source forever.
GitHub Sponsors — automatic verification:
familiar activateOpens a GitHub Device Flow login. familiar verifies your sponsorship via the GitHub GraphQL API. No tokens stored locally; result is cached for 30 days.
爱发电（Afdian） — manual activation code:
After sponsoring at afdian.com/a/Lief-ai, DM me your GitHub username and I'll send back an activation code:
familiar activate-code <your-code>If you fork this project, override the GitHub OAuth client ID and sponsor target:
export FAMILIAR_GITHUB_CLIENT_ID=Iv1.your-oauth-app-id
export FAMILIAR_SPONSOR_TARGET=your-github-loginRegister your OAuth App at https://github.com/settings/developers with device flow enabled.
Your pet's affection grows from 0 (陌生) to 100 (灵魂伴侣) based on how you interact:
/pet—+1/feed—+3(1h cooldown)/play—+2- Long Claude session (>1h) —
+5per hour - 24h no interaction —
-2(gentle decay)
Your pet's mood updates based on Claude Code state — they react to errors, completions, rate limits, and idle time.
npx claude-familiar uninstallThis removes the statusline + hooks from your Claude Code settings. Pet state in ~/.familiar/ is preserved by default.
Pet state lives at ~/.familiar/state.json — safe to inspect, edit, or back up.
Environment variables:
FAMILIAR_HOME— override the state directory (default:~/.familiar)FAMILIAR_MODEL— override the Claude model used for personality replies (default: same model your Claude Code uses)FAMILIAR_MEMORY_DIR— opt-in: a directory of.mdfiles the pet reads to personalize replies (e.g.~/.claude/projects/-/memory/). Each file is redacted before being sent to the model. Default: disabled.FAMILIAR_BRAIN— pick how the pet generates replies:cli(default) — spawnclaude -p, reuse your Claude Code login. No API key required.api— call the Anthropic SDK directly usingANTHROPIC_API_KEY.template— disable the LLM entirely; pet always falls back to its hand-written lines.
Built by Lief.
MIT — see LICENSE.
