claude-pet

A Tamagotchi-style ASCII pet that lives in the Claude Code status line. One emoji, one 20×8 LCD frame. Eats prompts, gets fed tokens, evolves through 5 stages, dies if neglected for 3 days.

╭──────────────────╮
│        ✨        │  ★ Mochi · baby · Lv.3
│                  │  ♥♥♥♥♥  🍴 ▰▰▰▰▰▱▱▱  😊 ▰▰▰▰▰▰▰▱
│      🦆          │  ✦ ▰▰▰▰▱▱▱▱▱▱ 32/80
│                  │  turn  in 1.2k · out 340 · cc 5.0k · cr 12.0k
│        💤        │  total in 12k · out 4.5k · cc 30k · cr 80k
│                  │
╰──────────────────╯  🧠 4% ctx  │  ⏱ 5h ▰▰▱▱▱ 40% 2h15m  │  📅 7d ▰▰▰▱▱ 55% 3d4h
─────...
[zenn@host | Claude: Opus 4.7 | claude_usage (master)]

What you get

• One emoji pet, your pick: default 🦆, change anytime with pet.sh set-emoji 🐱
• 20×8 LCD frame: programmatically rendered, pet wanders to a random position each refresh
• 5 evolution stages: egg → baby → child → teen → adult (stage controls decoration, not the emoji — egg is special-cased to 🥚 because it hasn't hatched)
• Stats: hunger, happiness, HP, XP, level
• Decay & death: hunger -2/h, happiness -1/h; HP drains if either hits 0; 3-day idle = neglect death (💀 in LCD)
• Hooks: UserPromptSubmit feeds it; Stop parses transcript token usage and feeds proportionally
• CLI actions: pet.sh meal | snack | play | clean — for 30s after, the action emoji (🍖 🍪 ⚽ 🛁) appears next to the pet
• Night mode: 22:00–06:00 local time, 💤 hovers above the pet
• Quota integration: 5h / 7d usage % + reset countdown + context-window % straight from Claude Code's statusLine stdin (Pro/Max only) — zero API calls, displayed live and feeds back into hunger/xp bonuses
• Telegram notifications: turn complete, duration, quota, pet status — all in one message
• /pet slash command: preview LCD for every stage

Requirements

• macOS or Linux — pure bash, no platform binaries
• jq (brew install jq / apt install jq)
• python3 (system Python works)
• Claude Code Pro/Max subscription (for the live 5h/7d quota row — gracefully hidden otherwise)
• A terminal with truecolor + emoji rendering (iTerm2 / Ghostty / WezTerm / Terminal.app / GNOME Terminal / Konsole / etc.)

Install

git clone <this repo> claude-pet
cd claude-pet
bash install.sh

The installer:

1. Copies pet.sh to ~/.claude/pet/
2. Hatches a default pet (Mochi, 🦆) if you don't have one yet
3. Updates ~/.claude/settings.json:
   • statusLine → pet.sh render
   • UserPromptSubmit hook → pet.sh feed-prompt
   • Stop hook → pet.sh feed-stop
4. Drops ~/.claude/commands/pet.md so /pet works as a slash command

Existing Telegram / other hooks are preserved (the installer matches by command and only replaces the pet entries).

Restart Claude Code afterwards.

Optional: Telegram notifications

Add to ~/.zshrc:

export TG_BOT_TOKEN=<your bot token>
export TG_CHAT_ID=<your chat id>

The Stop hook will send a turn-complete message with task / duration / quota / pet status.

Optional: Tune the bottom rule width

If status line wraps oddly in your terminal:

export PET_RULE_WIDTH=120   # default 80 (set 0 to disable rule)

Usage

~/.claude/pet/pet.sh stats                   # JSON dump of state
~/.claude/pet/pet.sh hatch <name> [emoji]    # start a new pet (default emoji 🦆)
~/.claude/pet/pet.sh set-emoji <emoji>       # change pet emoji without resetting
~/.claude/pet/pet.sh rename <name>           # change name without resetting
~/.claude/pet/pet.sh dance                   # 3-second wiggle animation
~/.claude/pet/pet.sh preview [stage]         # render LCD for one or all stages
~/.claude/pet/pet.sh meal                    # +30 hunger, +5 happy, +2 xp
~/.claude/pet/pet.sh snack                   # +8 hunger, +15 happy, +1 xp
~/.claude/pet/pet.sh play                    # -5 hunger, +25 happy, +3 xp
~/.claude/pet/pet.sh clean                   # +5 happy, +1 xp
~/.claude/pet/pet.sh debug-set <field> <value>   # cheats

In-Claude:

• /pet — preview LCD for every stage
• /pet teen — preview just one

Customizing your pet emoji

The pet is just one emoji you pick. Default is 🦆. Change it any time:

~/.claude/pet/pet.sh set-emoji 🐱
~/.claude/pet/pet.sh set-emoji 🦊

The choice persists in ~/.claude/pet/state.json (field pet_emoji) and survives reinstalls. Egg stage always shows 🥚 (since it hasn't hatched yet); your chosen emoji takes over from baby onwards. Death replaces the emoji with 💀.

For best results, pick a single double-width emoji (most face/animal/object emojis qualify). Multi-codepoint sequences (flags, ZWJ families) may render at unexpected widths in some terminals.

Files

claude-pet/
├── README.md          # this file
├── install.sh         # one-shot installer
├── pet.sh             # main script (status line, hooks, LCD render)
├── CLAUDE.md          # notes for Claude Code instances editing this repo
└── MECHANICS.md       # full game rules / thresholds reference (zh-tw)

Mechanics

Stage	Unlock
egg	start
baby	XP ≥ 10 or age ≥ 1h
child	XP ≥ 80 or age ≥ 6h
teen	XP ≥ 300 or age ≥ 24h
adult	XP ≥ 800 or age ≥ 72h

Hooks award:

• UserPromptSubmit: hunger +5, xp +1, prompt_count +1
• Stop: happiness +10, food based on token bracket (snack <1k / meal 1k–10k / feast 10k+), XP via token-weighted formula ((in + 5·out + 2·cc + cr) / 5000, +1 floor), plus avg(5h%, 7d%)/10 hunger boost. Tunable via TOKEN_W_* and TOKEN_DIVISOR env vars.

See MECHANICS.md for the full rules reference.

License

MIT (or whatever — it's an ASCII pet, do what you want).