<2-3 sentences summarising what the project addresses and solves, the target audience, and the benefit.> Claude Code Tamagotchi provides a real-time behavioral enforcement system for Claude Code, integrated as a virtual pet in the statusline. It monitors AI actions, detects instruction violations, and can interrupt misbehavior, acting as a safety net for AI accountability. Targeted at developers using Claude Code, it offers enhanced AI control and a companionable coding experience.

How It Works

The system combines real-time observation with an experimental AI-powered violation detection. Claude Code's actions are analyzed via a Groq LLM for rapid context building (50ms response) from user requests, AI actions, and pet state. This analysis influences the pet's mood and can trigger alerts for instruction violations. Violation detection acts as a pre-hook, capable of interrupting and blocking non-compliant operations. The pet's state and observations are displayed in the statusline.

Quick Start & Requirements

• Prerequisites: Claude Code, Bun runtime.
• Installation:
  • Global: bun add -g claude-code-tamagotchi (or npm), update ~/.claude/settings.json for statusline. Violation detection requires manual setup.
  • Clone & Auto-Setup: git clone https://github.com/Ido-Levi/claude-code-tamagotchi.git, cd claude-code-tamagotchi, ./setup.sh. Installs dependencies, commands, statusline, and violation detection hook.
• AI Features: Requires Groq API key (https://console.groq.com/keys). Enable via ./enable-feedback.sh or environment variables (PET_FEEDBACK_ENABLED, GROQ_API_KEY, PET_VIOLATION_CHECK_ENABLED). Violation detection needs PreToolUse hook configuration in ~/.claude/settings.json.
• Resource Footprint: Local execution with Groq API calls. Setup is quick, described as "30-Second Install".

Highlighted Details

• Real-time behavioral enforcement and AI accountability for Claude Code.
• Virtual pet interface in the statusline with dynamic mood and needs (hunger, energy, cleanliness, happiness).
• Experimental AI violation detection for unauthorized_action, refused_request, excessive_exploration, wrong_direction.
• Interaction via Claude Code slash commands (e.g., /pet-feed) or terminal CLI.
• Leverages Groq LLM for low-latency AI analysis.

Maintenance & Community

The project encourages contributions via pull requests for new thoughts, bug fixes, features, and documentation, as detailed in CONTRIBUTING.md. No specific community links (Discord/Slack) or roadmap are provided in the README.

Licensing & Compatibility

• License: MIT.
• Compatibility: Permissive MIT license suitable for commercial use and closed-source linking.

Limitations & Caveats

The behavioral enforcement system is experimental and may produce false positives, requiring user feedback for tuning. Global installation does not enable violation detection by default, necessitating manual configuration.