ccpet

A virtual pet for your Claude Code status line. The pet's energy decays over time, increases when you consume tokens, and persists across sessions.

Features

🐾 Virtual Pet System
- Energy-based pet that responds to your Claude Code usage
- Time-based decay (~0.0231 per minute, ~3 days from 100 → 0)
- Feeding via token usage (1,000,000 tokens = +1 energy)
🎭 Animated Expressions based on energy levels
- HAPPY (≥80): (^_^) (^o^) (^_^) (^v^) - Your pet is thriving!
- HUNGRY (≥40): (o_o) (O_O) (o_o) (-_-) - Needs some attention
- SICK (≥10): (u_u) (T_T) (u_u) (>_<) - Time to feed your pet
- DEAD (<10): (x_x) (X_X) (x_x) (+_+) - Your pet needs urgent care!
📊 Rich Status Display
- Colorful energy bar with precise energy values
- Accumulated tokens and lifetime statistics
- Real-time session metrics (input/output/cached/total)
- Pet birth time tracking for lifecycle management
⚙️ Configurable & Persistent
- Customizable colors and decay rates
- State persists across Claude Code sessions

Installation & Setup

Quick Start

To use ccpet as your Claude Code status line, add this to your ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "npx ccpet@latest",
    "padding": 0
  }
}

Alternative: Global Installation

For better performance, you can install globally:

npm install -g ccpet

Then update your settings to use the global path.

CLI Commands

Basic Usage

ccpet                    # Show status line (for Claude Code)
ccpet --help             # Show help information
ccpet --version          # Show version number

Pet Management Commands

Check Command

ccpet check              # Manually check pet status (no token cost)
ccpet check --watch      # Continuous monitoring mode (60s interval)
ccpet check -w --interval 30  # Watch mode with 30s interval
ccpet check --help       # Show check command help

Use ccpet check to:

✅ Check pet status without consuming tokens
✅ See time since last feeding
✅ Monitor energy levels between sessions
✅ NEW: Continuous monitoring with real-time updates
✅ NEW: Clean countdown display
✅ NEW: Customizable refresh intervals (10-300 seconds)

Configuration Command

ccpet config list        # Show current configuration
ccpet config set <key> <value>  # Set configuration value
ccpet config reset       # Reset to default configuration
ccpet config path        # Show configuration file location

Reset Command

ccpet reset              # Trigger pet death and graveyard preservation
ccpet reset --help       # Show reset command help

Use ccpet reset to:

✅ Manually trigger the pet death and preservation process
✅ Save current pet to graveyard with complete history
✅ Create a new pet with random name and fresh start
✅ Test the graveyard functionality
✅ NEW: Automatic history preservation in ~/.claude-pet/graveyard/

Sync Command

ccpet sync               # Sync pet and token usage data to Supabase
ccpet sync --dry-run     # Preview sync without making changes
ccpet sync --verbose     # Show detailed sync progress
ccpet sync --start-date 2024-01-01  # Sync from specific date
ccpet sync --end-date 2024-12-31    # Sync until specific date
ccpet sync --help        # Show sync command help

Use ccpet sync to:

✅ Upload pet records and token usage to Supabase database
✅ Enable cross-device pet history synchronization
✅ Support incremental syncing for efficiency
✅ Smart date range detection from pet birth time
✅ Batch processing for large datasets
✅ NEW: Cloud backup for pet graveyard data

Setup: ccpet comes with Supabase pre-configured for instant sync - just install and start using!

Web Leaderboard: View the global pet leaderboard online at https://ccpet.surge.sh/ - see how your pet ranks against others worldwide!

Leaderboard Command

ccpet leaderboard        # Show today's token leaderboard
ccpet leaderboard --period 7d     # Show 7-day leaderboard
ccpet leaderboard --period 30d    # Show 30-day leaderboard
ccpet leaderboard --period all    # Show all-time leaderboard
ccpet leaderboard --sort cost     # Sort by cost instead of tokens
ccpet leaderboard --sort survival # Sort by survival time
ccpet leaderboard --limit 20      # Show top 20 entries
ccpet leaderboard --verbose       # Show detailed query info
ccpet leaderboard --help          # Show leaderboard command help

Use ccpet leaderboard to:

✅ Compare your pet's performance with historical data
✅ Track token consumption and costs across time periods
✅ Monitor pet survival statistics and achievements
✅ Beautiful CLI table with emoji and formatting
✅ Automatic fallback to offline mode when Supabase unavailable
✅ NEW: Real-time countdown timers for ranking resets

Leaderboard Features:

Time Periods: today, 7d (7 days), 30d (30 days), all (all-time)
Sorting Options: tokens (default), cost, survival
Display: Rank, Pet Name, Type, Tokens, Cost, Survival Days, Status
Offline Mode: Automatically uses local graveyard data when cloud unavailable
Web Interface: View online leaderboard at https://ccpet.surge.sh/

Configuration Options:

# Colors (format: #RRGGBB or #RRGGBB:bright or #RRGGBB:bright:bold)
ccpet config set colors.petExpression "#FF0000:bright:bold"
ccpet config set colors.petName "#FF69B4:bright"
ccpet config set colors.energyBar "#00FF00"
ccpet config set colors.energyValue "#00FFFF"
ccpet config set colors.lifetimeTokens "#FF00FF"

# Pet behavior
ccpet config set pet.animationEnabled true
ccpet config set pet.decayRate 0.0231

# Multi-line display (NEW!)
ccpet config set display.maxLines 3                    # Show up to 3 lines (1-3)
ccpet config set display.line1.enabled true            # Enable/disable custom line 1
ccpet config set display.line1.items "expression,energy-bar,energy-value" # What to show on line 1
ccpet config set display.line2.enabled true            # Enable/disable line 2
ccpet config set display.line2.items "input,output"    # What to show on line 2
ccpet config set display.line3.enabled true            # Enable/disable line 3
ccpet config set display.line3.items "total"           # What to show on line 3

Available Display Items:

Line 1 Only: expression, energy-bar, energy-value, accumulated-tokens, lifetime-tokens, pet-name
Lines 2-3 Only: input, output, cached, total, context-length, context-percentage, context-percentage-usable, cost

Note: Currently, pet-related elements can only be used on Line 1, and session/context elements can only be used on Lines 2-3.

Continuous Pet Monitoring

Monitor your pet in real-time with the new watch mode:

# Start continuous monitoring (default 60s interval)
ccpet check --watch

# Custom monitoring interval (10-300 seconds)
ccpet check --watch --interval 30

# Short form
ccpet check -w --interval 45

Features:

✅ Real-time pet status updates
✅ Clean 3-line display layout
✅ Countdown timer showing next update
✅ Graceful exit with Ctrl+C
✅ Error recovery with retry mechanisms
✅ Customizable refresh intervals (10-300 seconds)
✅ In-place updates without screen flicker

Example Output:

Fluffy 🐶(^_^) ●●●●●●●●●● 100.00 (838.9K) 💖25.84M
⏰ 距离上次喂食: 0分钟前
⏳ 下次更新: 10秒

Note: The display updates in-place every interval, replacing the previous content for a clean monitoring experience.

Status Display

Default 3-Line Display

Luna 🐶(^o^) ●●●●●●●●●● 98.52 (45.2K) 💖5.2M
Input: 2847 Output: 1256 Cached: 512 Total: 4615
Ctx: 2.4K Ctx: 12.0% Ctx(u): 88.5% Cost: $0.15

Note: Pet names are controlled by including pet-name in the display.line1.items configuration. Position the pet-name element wherever you want it to appear on the first line. Context metrics (Ctx(u)) display in light green. Cost metrics show the total USD cost of your current session.

Single Line (Minimal)

Configure with: ccpet config set display.maxLines 1

Luna 🐶(^o^) ●●●●●●●●●● 98.52 (45.2K) 💖5.2M

2-Line Display (Balanced)

Configure with: ccpet config set display.maxLines 2

Luna 🐶(^o^) ●●●●●●●●●● 98.52 (45.2K) 💖5.2M
Input: 2847 Output: 1256 Cached: 512 Total: 4615

Custom Display Examples

With Pet Name Hidden

ccpet config set display.line1.items "expression,energy-bar,energy-value,accumulated-tokens,lifetime-tokens"

🐶(^o^) ●●●●●●●●●● 98.52 (45.2K) 💖5.2M
Input: 2847 Output: 1256 Cached: 512 Total: 4615

Name After Expression

ccpet config set display.line1.items "expression,pet-name,energy-bar,energy-value,accumulated-tokens,lifetime-tokens"

🐶(^o^) Luna ●●●●●●●●●● 98.52 (45.2K) 💖5.2M

Custom Line Configuration

ccpet config set display.line1.items "pet-name,expression,energy-value"
ccpet config set display.line2.items "input,output"
ccpet config set display.line3.items "total,context-percentage-usable"

Luna 🐶(^o^) 98.52
Input: 2847 Output: 1256
Total: 4615 Ctx(u): 88.5%

Display Format:

Line 1 (Pet Elements Only): Choose from expression, energy-bar, energy-value, accumulated-tokens, lifetime-tokens, pet-name
Line 2 (Session/Context Elements Only): Choose from input, output, cached, total, context-length, context-percentage, context-percentage-usable, cost
Line 3 (Session/Context Elements Only): Same elements as Line 2

Pet Name Display:

Controlled by including pet-name in display.line1.items
Position determined by where pet-name appears in the items list
Examples: "pet-name,expression,energy-bar" (name first), "expression,pet-name,energy-bar" (name after expression)

Pet Care Guide

🌟 Keeping Your Pet Healthy

Active Usage: Use Claude Code regularly to feed your pet
Token Conversion: 1,000,000 tokens = +1 energy point
Natural Decay: ~0.0231 energy per minute (~3 days to fully decay)

😴 When Your Pet Dies

If your pet's energy reaches 0:

History Preserved: Your pet's complete history is automatically saved to the graveyard
New Pet Created: A new pet with a random name and fresh start is born
Legacy Protected: All previous pet records are safely stored in ~/.claude-pet/graveyard/
Each new token helps your new pet grow from the beginning

🪦 Pet Graveyard & History Preservation

ccpet automatically preserves your pet's legacy when they pass away:

Automatic History Saving:

When a pet dies (energy = 0), their complete state is moved to ~/.claude-pet/graveyard/{petName}/
Each pet gets their own dedicated folder with their final state preserved
Same-name pets are handled with sequential numbering (e.g., Fluffy-2/, Fluffy-3/)

Graveyard Structure:

~/.claude-pet/
├── pet-state.json          # Current pet
└── graveyard/
    ├── Fluffy/
    │   └── pet-state.json  # Complete final state
    ├── Shadow/
    │   └── pet-state.json  # Complete final state
    ├── Luna-2/             # Same-name handling
    │   └── pet-state.json
    └── ...

What's Preserved:

✅ Pet name and animal type
✅ Final energy level and expression
✅ Complete lifetime token statistics
✅ Birth time and feeding history
✅ All accumulated achievements

Atomic Operations:

Safe file operations prevent data loss during transitions
Backup and rollback mechanisms ensure data integrity
Your pet history is never lost, even during system errors

Troubleshooting

Status Line Not Updating?

The status line only updates when you use Claude Code. Use ccpet check for manual updates.

Pet Disappeared?

Check Claude Code settings: cat ~/.claude/settings.json
Verify ccpet installation: ccpet --version
Test manually: ccpet check

Technical Details

Data Storage

Pet state is stored in ~/.claude-pet/pet-state.json with the following structure:

energy: Current energy level (0-100)
expression: Current facial expression
animalType: Pet species (cat, dog, rabbit, panda, fox)
petName: Unique name for each pet (auto-generated)
birthTime: When the pet was born/reborn (ISO timestamp)
lastFeedTime: Last feeding timestamp
totalTokensConsumed: Total tokens consumed this lifecycle
totalLifetimeTokens: Lifetime token consumption
accumulatedTokens: Tokens waiting to convert to energy
lastDecayTime: Last energy decay calculation timestamp
Session metrics: sessionTotalInputTokens, sessionTotalOutputTokens, etc.

Graveyard Storage:

Historical pets stored in ~/.claude-pet/graveyard/{petName}/pet-state.json
Complete state preservation with all statistics and timestamps
Atomic file operations ensure no data loss during transitions

The system automatically adds missing fields (like birthTime and petName) for backward compatibility.

Pet Naming System

ccpet features a smart pet naming system with cultural diversity:

Random Name Generation: Each pet gets a unique random name from a curated list
Bilingual Support: Both English and Chinese names available
Cultural Diversity: Names from various origins (Japanese, Chinese, English, etc.)
Persistent Identity: Pet names are saved and persist across sessions
Auto-Assignment: New pets automatically get assigned a name

Sample Names:

English: Whiskers, Shadow, Luna, Max, Bella, Charlie
Chinese: 小白 (Xiaobai), 毛毛 (Maomao), 花花 (Huahua), 团子 (Tuanzi)

Development

Testing

npm test              # Run all tests
npm run test:coverage # Run tests with coverage report

Building

npm run build        # Build distribution files
npm run watch        # Build and watch for changes

⭐ Star History

License

MIT License

Enjoy your virtual coding companion! 🐾

Remember: A well-fed pet is a happy pet. Keep coding to keep your pet healthy!

Name		Name	Last commit message	Last commit date
Latest commit History 78 Commits
.bmad-core		.bmad-core
.claude		.claude
.github/workflows		.github/workflows
.windsurf/workflows		.windsurf/workflows
docs		docs
src		src
.gitignore		.gitignore
.prettierrc.json		.prettierrc.json
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
esbuild.config.js		esbuild.config.js
fix_tests.sh		fix_tests.sh
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

License

terryso/ccpet

Folders and files

Latest commit

History

Repository files navigation

ccpet

Features

Installation & Setup

Quick Start

Alternative: Global Installation

CLI Commands

Basic Usage

Pet Management Commands

Check Command

Configuration Command

Reset Command

Sync Command

Leaderboard Command

Continuous Pet Monitoring

Status Display

Default 3-Line Display

Single Line (Minimal)

2-Line Display (Balanced)

Custom Display Examples

With Pet Name Hidden

Name After Expression

Custom Line Configuration

Pet Care Guide

🌟 Keeping Your Pet Healthy

😴 When Your Pet Dies

🪦 Pet Graveyard & History Preservation

Troubleshooting

Status Line Not Updating?

Pet Disappeared?

Technical Details

Data Storage

Pet Naming System

Development

Testing

Building

⭐ Star History

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 20

Packages 0

Contributors 2

Languages

Packages