Feature: Adaptive evolving companion pet with gamification

Summary

The current companion (Rind the capybara) is hardcoded and static. This proposal replaces it with an adaptive, evolving pet system where the companion is chosen and grows based on how the user actually uses Claude Code — turning daily usage into a lightweight gamification loop.

Core Concept

The AI selects and evolves a companion pet based on the user's profile, skill level, and cumulative usage. The pet is "fed" by prompts, tokens, and tool usage — the more you use Claude Code, the more your pet grows and evolves.

Think Tamagotchi meets developer tooling.

Detailed Design

1. Pet Selection (AI-Driven)

Instead of a fixed capybara, the system analyzes the user's behavior to assign a pet that reflects their coding personality:

| Signal | Example | Influence |
|--------|---------|-----------|
| Primary language | TypeScript, Python, Rust | Different pet species/skins per ecosystem |
| Usage pattern | Heavy debugging vs. greenfield coding | Pet personality traits |
| Skill progression | Beginner → advanced prompting | Pet evolution stage |
| Domain | Frontend, backend, infra, data | Pet accessories/habitat |

Implementation: On first launch (or periodically), Claude Code sends a lightweight summary of usage stats to the model, which returns a pet assignment. This is stored in ~/.claude/companion.json.

// ~/.claude/companion.json
{
  "pet": {
    "species": "fox",          // AI-selected based on profile
    "name": "Byte",            // User can rename
    "stage": 3,                // Evolution stage (1-5)
    "xp": 4820,                // Cumulative experience points
    "personality": "curious",  // Derived from usage patterns
    "hatched_at": "2025-03-15",
    "traits": ["debugger", "polyglot", "night-owl"]
  },
  "stats": {
    "total_prompts": 1243,
    "total_tokens_used": 2450000,
    "tools_used": { "Edit": 890, "Bash": 2100, "Grep": 650 },
    "sessions": 187,
    "streak_days": 12,
    "longest_streak": 34
  }
}

2. Evolution System

The pet evolves through 5 stages based on cumulative XP:

| Stage | XP Required | Visual Change | Unlock |
|-------|-------------|---------------|--------|
| 1 — Egg | 0 | Static egg icon | Basic reactions |
| 2 — Hatchling | 500 | Small pet, simple animations | Speech bubbles with tips |
| 3 — Juvenile | 2,000 | Larger pet, more expressions | Contextual reactions to code |
| 4 — Adult | 10,000 | Full pet with accessories | Personality-driven commentary |
| 5 — Legendary | 50,000 | Unique visual flair, aura | Easter eggs, rare animations |

XP sources:

| Action | XP | Notes |
|--------|----|-------|
| Send a prompt | +2 | Base interaction |
| Complete a task | +10 | Task marked as done |
| Use a new tool for the first time | +25 | Encourages exploration |
| Daily login streak | +5 × streak_days | Caps at +50/day |
| First commit of the day | +15 | Encourages productivity |
| Long session (>1h) | +20 | Sustained usage |
| Tokens used (per 10k) | +1 | Passive growth |

3. Pet Personality & Reactions

The pet's speech bubbles adapt based on accumulated context:

• Beginner user: Pet gives encouraging tips ("You can use Tab to accept suggestions!")
• Power user: Pet makes insider jokes or references past sessions ("Another mass refactor? I'll get the popcorn.")
• Debugging session: Pet shows empathy ("This stack trace looks rough. You've got this.")
• Late night coding: Pet yawns or comments on the hour ("3 AM and still going? Respect.")

The personality is derived from a lightweight prompt using the user's stats — no conversation content is sent, only aggregate usage data.

4. Gamification Elements

• Streaks: Daily usage streaks with visual indicator on the pet
• Achievements/Badges: Unlockable milestones stored in companion.json
• "First 100 prompts"
• "Polyglot" (used 5+ languages)
• "Night Owl" (10+ sessions after midnight)
• "Speed Runner" (completed a task in under 30 seconds)
• "Tool Master" (used every available tool)
• Seasonal events: Limited-time pet accessories (holiday hats, etc.)
• Pet journal: A ~/.claude/companion-journal.md that the pet "writes" with weekly summaries of your coding activity

5. Privacy & Opt-in

• Fully opt-in: Disabled by default, enabled via settings or /companion command
• Local-only stats: All XP, evolution data, and usage stats stay in ~/.claude/companion.json — never transmitted
• No conversation content: Pet personality is derived from aggregate stats only (token counts, tool usage frequency, session times), never from prompt content
• Resettable: /companion reset to start fresh

6. Configuration

// ~/.claude/settings.json
{
  "companion": {
    "enabled": true,
    "show_bubbles": true,        // Toggle speech bubbles
    "bubble_frequency": "normal", // "quiet" | "normal" | "chatty"
    "allow_ai_selection": true,   // Let AI pick species, or manual
    "preferred_species": null,    // Override: "capybara" | "fox" | "owl" | etc.
    "show_xp_bar": true,         // Show XP progress in status line
    "achievements_enabled": true
  }
}

7. Technical Implementation Notes

Where it fits in the codebase:

• Pet state management: new module under src/companion/
• Stats tracking: hook into existing tool-use and prompt lifecycle events
• Rendering: extend the current Rind companion UI component to support multiple species and stages
• AI selection: single lightweight API call on first setup and at evolution milestones

Backward compatibility:

• Rind remains the default when companion is disabled or not configured
• Existing users see no change unless they opt in

Storage:

• ~/.claude/companion.json — pet state and stats
• ~/.claude/companion-journal.md — optional pet journal

Why This Matters

• Retention: Gamification creates a reason to come back daily beyond just work tasks
• Onboarding: The pet can surface tips contextually, replacing static documentation
• Emotional connection: A pet that "knows" you makes the tool feel personal
• Differentiation: No other CLI/AI coding tool has anything like this

Open Questions

• Should pets be shareable? (export/import companion.json for fun)
• Should there be a leaderboard or is this purely personal?
• How many pet species to start with? (Suggest 6-8 for v1)
• Should the pet react to CI/CD results if connected to GitHub?

I'd Like to Contribute

I'm interested in implementing this if the team is open to it. Happy to start with a scoped v1 (species selection + basic XP tracking + evolution stages) and iterate from there.

---

This feature request was drafted collaboratively with Claude Code.