[Feature] Buddy evolution system: XP from token usage + personality drift from conversations

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Summary

Two complementary enhancements to the /buddy system that transform it from a static
novelty into a living companion that reflects how you actually use Claude Code.

---

Problem statement

The current buddy is fully static after hatch. Species, rarity, stats, and personality
are fixed forever. A developer who has run 10M tokens across hundreds of sessions has
the exact same companion as someone who tried /buddy once.

There is no feedback loop between usage and the companion — the "watcher" watches,
but never learns.

---

Proposed changes

1. XP progression from token usage and session activity

Track cumulative usage and surface it as companion XP. Suggested tier thresholds:

| Tier | XP threshold | Visual change |
|------------|------------------|--------------------------------------|
| Hatchling | 0 | Base sprite |
| Juvenile | 100K tokens | Corner energy markers, bolder idle |
| Adult | 1M tokens | Species-specific pattern overlay |
| Elder | 10M tokens | Ambient glow effect, unique idle |
| Ancient | 50M tokens | Rare aura, distinct speech style |

XP sources (illustrative, not prescriptive):

• Tokens processed (primary signal)
• Session count
• Streak multiplier for consecutive days

This does not require server-side state. Token counts already exist in local config
(~/.claude.json). A simple accumulator persisted locally is sufficient for an MVP.

2. Personality drift from conversation patterns

The current Soul layer generates a personality once and freezes it. Instead, allow the
personality description to evolve gradually based on observed session patterns.

Proposed mechanism:

• The companion reaction API already receives transcript and stats per call
• Periodically (e.g. every 50 sessions or on tier-up), re-prompt the Soul layer with a

diff of recent interaction patterns: dominant tool types, error frequency, language
mix, time-of-day patterns

• The updated personality description is stored back to ~/.claude.json as a delta,

not a full replacement — preserving continuity while allowing drift

Example: a companion hatched as "curious and methodical" might drift toward
"battle-hardened and dry" after 500 debugging sessions, or "quietly enthusiastic" after
months of greenfield work.

The key constraint: drift should feel gradual and earned, not jarring. A changelog
entry in the companion record (e.g. personalityHistory: [...]) could let users see
how their buddy has changed over time.

---

Why this fits the existing architecture

• Bones layer is untouched. Species, rarity, shiny status remain deterministic from

account ID. No fairness issues.

• Soul layer already supports re-generation. Deleting the companion key forces a

re-hatch today — this proposal formalizes a controlled version of that mechanism.

• No blockchain, no NFTs, no trading. The companion remains non-transferable and

account-bound. The value is personal, not speculative.

• Local-first. Both XP accumulation and personality history can live in

~/.claude.json with no new backend infrastructure required for an MVP.

---

Prior art / related issues

• #41684 — RPG evolution for /buddy (XP from token usage)
• #41867 — Buddy customization, progression system & monetization
• #41908 — Customizable buddy pets, renaming, behavior & gamification

This proposal focuses specifically on the usage-driven XP and personality drift
mechanisms, keeping scope narrow enough to be actionable.

---

Acceptance criteria (suggested)

• [ ] Companion tier is visible on /buddy card output
• [ ] XP progress is shown (e.g. 12,450 / 100,000 XP to Juvenile)
• [ ] Personality description updates after meaningful usage milestones
• [ ] Personality history is accessible (e.g. /buddy history)
• [ ] Existing companions are not reset — XP initializes from existing token count in config

---

Tested on Claude Code v2.1.90. Daily user, ~840 sessions across personal and work projects.

Proposed Solution

The companion's /buddy card should display a tier and XP progress bar:

Fenwick the Robot [Adult ██████░░ 1.2M / 10M XP to Elder]
DEBUGGING ████████░░ 81 SNARK ██░░░░░░░░ 23

Personality drift: every ~50 sessions, the Soul layer re-prompts with a summary
of recent interaction patterns (dominant tools, error rate, languages used). The
updated description is appended as a delta to ~/.claude.json, preserving history:

personalityHistory: [
{ date: "2026-01-01", description: "curious and methodical" },
{ date: "2026-04-01", description: "battle-hardened, dry humor" }
]

New commands:

• /buddy history — show personality changelog
• /buddy xp — show XP breakdown by source

Alternative Solutions

• any-buddy (https://github.com/cpaczek/any-buddy): patches the binary to choose

a different species/rarity, but stats remain static and there is no progression.

• Manually deleting the companion key in ~/.claude.json to force a re-hatch, but

this resets everything and loses the Soul entirely.

• Neither workaround provides usage-driven growth or personality evolution.

Priority

Low - Nice to have

Feature Category

CLI commands and flags

Use Case Example

1. I've been using Claude Code daily for backend development (Node.js, MySQL, AWS)

across hundreds of sessions over several months.

1. I run /buddy card and see the exact same stats as day one — no reflection of

the work we've done together.

1. With XP progression, I'd see my companion advance to "Adult" tier after hitting

1M tokens, with a visible overlay on the sprite.

1. After months of heavy debugging sessions, the companion's personality description

gradually shifts to reflect that pattern — making it feel like a genuine shared
history rather than a frozen snapshot from hatch day.

Additional Context

Related issues: #41684, #41867, #41908

Similar retention mechanics validated in other tools:

• Duolingo streak owl (usage-driven state change)
• GitHub contribution graph (cumulative activity visualization)

Both XP accumulation and personality history can be stored locally in ~/.claude.json
— no new backend infrastructure needed for an MVP. The companion reaction API already
receives transcript and session context per call, making personality drift feasible
without architectural changes.