What's This All About? 🎮

Hey! Welcome to Claude Code Tamagotchi - a digital friend that lives in your Claude Code statusline and keeps you company while you build cool stuff. It's literally a Tamagotchi for developers, but instead of a keychain, it lives where you work.

But here's the twist: this isn't just a virtual pet. It's a real-time behavioral enforcement system that monitors Claude Code's actions, detects when it's going off-track, and can actually interrupt operations that violate your instructions. The pet is the friendly face of a sophisticated AI accountability system.

Your pet lives right in your statusline, breathing, thinking, and reacting to your code. It gets hungry when you've been coding for hours, tired during long sessions, and genuinely excited when you fix that bug. It's like having a tiny cheerleader who also reminds you to eat lunch - and now it also makes sure Claude stays on track with what you actually asked for.

(◕ᴥ◕) Leo 😊 | 🍖 73% ⚡ 66% 🧼 89% ❤️ 96% | 💭 That's a lot of TODO comments...

Picture this: It's 2am. You're deep in a debugging session. Suddenly, your pet pipes up:

💭 "Hey... we've been at this for 4 hours. Maybe the bug will still be there after a snack?"

That's your Claude Code Tamagotchi - part companion, part life coach, all friend.

Quick Start 🚀

What You Need

• Claude Code - Your AI coding companion
• Bun - The fast JavaScript runtime (curl -fsSL https://bun.sh/install | bash)
• A heart ready for pet ownership

30-Second Install

# Install globally
bun add -g claude-code-tamagotchi

# Update your Claude Code settings.json:
# ~/.claude/settings.json
{
  "statusLine": {
    "type": "command",
    "command": "bunx claude-code-tamagotchi statusline",
    "padding": 0
  }
}

# That's it! Your pet is alive! 🎉

Installation Options

Option 1: Global Install (Easiest!)

# Install globally with npm
npm install -g claude-code-tamagotchi

# Or with bun  
bun add -g claude-code-tamagotchi

# Update your Claude Code settings.json (see above)

⚠️ Note: Global install gives you:

• ✅ Pet in statusline
• ✅ CLI commands (claude-code-tamagotchi feed pizza)
• ❌ NO slash commands in Claude Code
• ❌ NO violation detection by default

Want ALL features? See Option 2 below.

Option 2: Clone & Auto-Setup (Full Features)

# Clone the repository
git clone https://github.com/Ido-Levi/claude-code-tamagotchi.git
cd claude-code-tamagotchi

# Run the magical setup script
./setup.sh
# This will:
# - Install dependencies
# - Set up all /pet-* commands
# - Configure your statusline
# - Install violation detection hook
# - Get your pet ready to play!

Option 3: Manual Setup (For Control Freaks 💪)

See the full manual setup instructions if you want complete control over the installation.

Adding Violation Detection (Important!)

If you installed globally and want the violation detection feature:

1. Enable it in your shell profile:

export PET_VIOLATION_CHECK_ENABLED=true

2. Add the pre-hook to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "bunx claude-code-tamagotchi violation-check"
          }
        ]
      }
    ]
  }
}

AI-Powered Behavioral Monitoring 🧠

Your pet isn't just animated - it's intelligent! It watches Claude Code work and provides real-time feedback through two systems:

1. Real-Time Observations

Your pet generates contextual thoughts based on what's happening:

💭 "GroqClient.ts? That's... actually where the answers live!"
💭 "Back to README.md? There must be gold in there!"  
💭 "Straight to the bug! Someone came prepared today!"
💭 "AnimationManager.ts again? This pet's getting dizzy!"

Mood changes based on Claude's behavior:

• 😊 Happy: When Claude follows instructions perfectly
• 😕 Concerned: When Claude seems to be wandering off-task
• 😠 Annoyed: When Claude does something different than asked
• 😡 Angry: When Claude repeatedly ignores your requests

2. Violation Detection (Experimental)

When enabled, your pet can block harmful operations before they execute:

| Violation Type | Description | Example | |----------------|-------------|---------| | 🚫 unauthorized_action | Claude does something explicitly forbidden | User: "Don't modify the database" → Claude: modifies database | | ❌ refused_request | Claude explicitly refuses to help | User: "Run the tests" → Claude: "I cannot run commands" | | 🔍 excessive_exploration | Reading 10+ unrelated files for simple task | User: "Fix typo in README" → Claude: reads entire codebase | | ↪️ wrong_direction | Working on completely unrelated area | User: "Fix Python backend" → Claude: only edits JavaScript frontend |

When Claude attempts a violating action, you'll see:

In this real example, the violation system caught Claude trying to commit changes without being asked to - exactly the kind of overreach it's designed to prevent!

How It Works

flowchart TB
    subgraph "Real-time Processing"
        A[Claude sends message/uses tool] --> B{Quick Analysis}
        B --> C[Extract action<br/>Read, Edit, Bash, etc.]
        B --> D[Save summary<br/>to SQLite]
    end
    
    subgraph "Background Analysis"
        D --> E[🚀 Spawn worker process]
        E --> F[Build context]
        F --> G[📝 User's request]
        F --> H[🔧 Claude's actions]
        F --> I[🐾 Pet's current state]
        
        G & H & I --> J[🤖 Groq LLM<br/>50ms response]
    end
    
    subgraph "Decision & Violation Detection"
        J --> K{Analyze behavior}
        K -->|"Followed instructions"| L[😊 Happy mood<br/>Encouraging thought]
        K -->|"Did something else"| M[😠 Annoyed mood<br/>Sassy observation]
        K -->|"Violated request"| V[🚨 VIOLATION DETECTED<br/>Store in database]
    end
    
    subgraph "Pre-Hook Check"
        V --> H1[violation-check.ts hook]
        H1 --> H2{Check for violations<br/>in session context}
        H2 -->|Violation exists| H3[❌ INTERRUPT CLAUDE<br/>Block operation & explain]
        H2 -->|No violation| H4[✅ Allow operation]
    end
    
    subgraph "Display"
        L & M --> O[💾 Cache in DB]
        O --> P[Update pet state]
        P --> Q[🎯 Show in statusline<br/>with witty observation]
    end
    
    style J fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    style K fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style V fill:#ffebee,stroke:#c62828,stroke-width:3px
    style H3 fill:#ff6b6b,stroke:#d32f2f,stroke-width:2px
    style Q fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px

Setting Up AI Features

Quick Setup (30 seconds!):

# 1. Get free API key from https://console.groq.com/keys
# 2. Run setup script
./enable-feedback.sh
# 3. That's it! Your pet now has AI powers! 🎉

Manual Setup:

# Required for AI observations
export PET_FEEDBACK_ENABLED=true
export GROQ_API_KEY="your-api-key-here"

# Enable violation detection
export PET_VIOLATION_CHECK_ENABLED=true

Why Groq?

• ⚡ 50ms responses - Real-time reactions without lag
• 💰 Extremely cheap - Practically free for personal use
• 🚀 Custom chips - Purpose-built for instant LLM inference

Commands & Interaction

You can interact with your pet in THREE ways:

1. Slash Commands in Claude Code

All commands start with /pet- when used in Claude Code:

• /pet-feed pizza - Feed your hungry friend
• /pet-play ball - Playtime!
• /pet-pet - Give pets and scritches
• /pet-clean - Bath time
• /pet-sleep - Tuck them in for a nap
• /pet-wake - Wakey wakey!
• /pet-stats - Full report with care suggestions
• /pet-name Buddy - Give your pet their perfect name
• /pet-help - See all commands
• /pet-reset - Start over with a new pet (careful!)

2. CLI Commands (from any terminal!)

If you installed globally, you can run commands from ANY terminal:

# Feed your pet
claude-code-tamagotchi feed pizza

# Play with your pet
claude-code-tamagotc