7.1 Buddy Companion - Claude Code Deep Dive

1

🐣 What Is BUDDY?

An unreleased virtual-pet system behind feature('BUDDY') flag. A small ASCII creature in the terminal corner with species, custom eyes, optional hat, five personality stats, rarity tier, AI-generated name and personality, idle animations, and speech bubbles.

💡 Bones vs Soul Split

Bones (species, eye, hat, rarity, stats) regenerate deterministically from hash(userId). Soul (name, personality, hatchedAt) persists in config.companion. Ensures tamper-proof rarity and forward compatibility.

2

🎲 Deterministic Generation

Mulberry32 PRNG

Seeded by hash(userId + 'friend-2026-401'). Identical sequences from same seed. Bun.hash() or FNV-1a fallback.

Rarity System

Weighted: Common 60%, Uncommon 25%, Rare 10%, Epic 4%, Legendary 1%. Stat floors scale with rarity. 1-in-100 shiny chance.

Stats

DEBUGGING, PATIENCE, CHAOS, WISDOM, SNARK. One peak stat, one dump stat, rest scattered. Legendary peaks can reach 130 before cap.

3

🎨 ASCII Art Engine

18 species, each with 3 animation frames stored as 5-line strings. Eyes substitute via {E} template placeholder. Hats inject into top row when blank. Idle sequence [0,0,0,0,1,0,0,0,-1,0,0,2,0,0,0] creates organic feel. -1 = blink frame.

💡 Species Obfuscation

One species name collides with a model codename in excluded-strings.txt. All 18 encoded via String.fromCharCode(hex) to keep literals out of the bundle while CI check stays armed.

4

💬 CompanionSprite Widget

React/Ink component with 500ms animation tick. Idle sequence for natural feel. Pet hearts animation (5 frames, 2.5s). Narrow terminal (<100 cols) collapses to single-line face. Fullscreen uses floating bubble component.

💡 Fullscreen vs Scrollback

Non-fullscreen: bubble inline beside sprite. Fullscreen: CompanionFloatingBubble renders separately in bottomFloat slot outside clipping region.

5

📝 Context Injection

Companion appears to Claude via companionIntroText() system prompt attachment. When user addresses companion by name, Claude steps aside in ONE line. Speech bubble (separate React component) handles the reply.

💡 Launch Window

April 1-7, 2026. Uses local time (not UTC) for 24-hour rolling wave across timezones - marketing decision for sustained social media buzz.

6

⭐ Rarity & Display

Rarity	Chance	Stars	Stat Floor	Hat?
Common	60%	★	5	Never
Uncommon	25%	★★	15	Yes
Rare	10%	★★★	25	Yes
Epic	4%	★★★★	35	Yes
Legendary	1%	★★★★★	50	Yes

📋 Resumo do Modulo

✅ BUDDY is a fully implemented Tamagotchi companion system, gated by feature flag, launching April 1, 2026.

✅ Creatures generate deterministically from Mulberry32 PRNG seeded by hash(userId + salt).

✅ Bones/soul split keeps rarity tamper-proof while storing only name, personality, hatchedAt to disk.

✅ All 18 species names runtime-construct from hex char codes to avoid build-output canary monitoring.

✅ Speech bubbles have two rendering paths: inline (scrollback) and floating (fullscreen).

✅ Companion injects as companion_intro attachment; model steps aside when user addresses companion by name.