familiar

A pixel-art pet companion for Claude Code CLI. Lives in your statusline. Reacts to your sessions. Grows with you.

Install

npx claude-familiar install

You'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.

Why familiar?

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 -p under the hood). No extra API key, no extra cost beyond your existing plan.
• Has persistent memory — reads CLAUDE.md and ~/.claude/projects/-/memory/ so the pet knows your project
• Open-core: 2 free pets + premium pet pack via sponsorship

Requirements

• Claude Code CLI installed and signed in
• Node.js 18+
• Any modern terminal with 24-bit ANSI color support

Mobile (Termius / iSH / etc.)

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.

Commands

| 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 |

Pets

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.

Activating sponsor status

GitHub Sponsors — automatic verification:

familiar activate

Opens 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>

For maintainers and forks

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-login

Register your OAuth App at https://github.com/settings/developers with device flow enabled.

How affection works

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) — +5 per 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.

MCP Server

familiar ships a built-in MCP server so Claude Code (and any MCP-compatible client) can query and interact with your pet programmatically.

Setup

Add to your ~/.claude/settings.json:

{
  "mcpServers": {
    "familiar": {
      "type": "stdio",
      "command": "familiar",
      "args": ["mcp"]
    }
  }
}

Then restart Claude Code. The server starts on-demand over stdio — no daemon, no ports.

Available tools

| Tool | Description | | --- | --- | | familiar_status | Get pet name, species, affection (0–100), mood, last interaction | | familiar_speak | Ask the pet to say something (personality-driven, LLM or template) | | familiar_interact | Pet / feed / play — raises affection, respects cooldowns | | familiar_remember | Persist a free-text memory note to ~/.familiar/memory.json |

Example

Once connected, Claude Code can call:

familiar_status → { "name": "Mochi", "affection": 72, "relationship": "挚友", ... }
familiar_speak  → "Mochi: 今天终于做完了，不容易。"

Uninstall

npx claude-familiar uninstall

This removes the statusline + hooks from your Claude Code settings. Pet state in ~/.familiar/ is preserved by default.

Configuration

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 .md files 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) — spawn claude -p, reuse your Claude Code login. No API key required.
  • api — call the Anthropic SDK directly using ANTHROPIC_API_KEY.
  • template — disable the LLM entirely; pet always falls back to its hand-written lines.

Author

Built by Lief.

License

MIT — see LICENSE.