{
  "markdown": "# claude-tamagotchi\n\nA persistent Tamagotchi creature that lives in your Claude Code status line. It evolves through emoji stages, has session-level moods, and can die from neglect — leaving behind an egg with inherited XP for the next generation.\n\n```\n🥚 Nugget ▰▰▰▰▰▰ ⬆1    (freshly hatched)\n🐥 Nugget ▰▰▰▰▱▱ ⬆3    (growing up)\n💀 Nugget ▱▱▱▱▱▱ ⬆3    (neglected too long)\n```\n\n## Install\n\nFirst, add the marketplace:\n\n```bash\n/plugin marketplace add ncrohn/ncrohn-plugins\n```\n\nThen install the plugin:\n\n```bash\n/plugin install claude-tamagotchi@ncrohn-plugins\n```\n\nOn your next session, a creature will hatch automatically with a random name and theme. You won't know what it is until Level 2 — every creature starts as an egg.\n\n## Status Line Setup\n\nAfter install, run `/tamagotchi setup` to add the creature to your status line. Or manually add this line to your `~/.claude/statusline-command.sh`:\n\n```bash\n# Tamagotchi creature\nif [ -f \"$HOME/.claude/tamagotchi/display.txt\" ]; then\n  status+=\"$(cat \"$HOME/.claude/tamagotchi/display.txt\")\"\nfi\n```\n\nIf you don't have a custom status line script yet, run `/statusline` in Claude Code to set one up first.\n\n## How It Works\n\n### Lifecycle\n\nYour creature is **persistent** — it lives across sessions and ages over time. Each session affects its mood, while long-term patterns affect its health and growth.\n\n**Session-level factors** (affect mood and display color):\n- Error rate in tool calls (stressed when things break)\n- Conversation length\n- Usage streaks (proud after 7+ consecutive days)\n\n**Long-term factors** (affect HP and XP):\n- Daily usage keeps your creature healthy (+10 HP per session)\n- Streaks give bonus recovery (+5 HP when streak > 3 days)\n- Neglect causes HP decay (-5 HP/day after a 2-day grace period)\n- XP is earned each session based on turns and tool usage\n\n### Evolution\n\nCreatures evolve through 5 emoji stages as they level up. Theme is random on each hatch:\n\n| Level | Default | Cat | Dragon | Plant |\n|-------|---------|-----|--------|-------|\n| 1 | 🥚 | 🥚 | 🥚 | 🥚 |\n| 2 | 🐣 | 🐱 | 🐛 | 🌱 |\n| 3 | 🐥 | 😺 | 🦎 | 🌿 |\n| 4 | 🐔 | 🐈 | 🐉 | 🪴 |\n| 5 | 🦅 | 🐈‍⬛ | 🐲 | 🌳 |\n\n### Death & Inheritance\n\nIf your creature's HP reaches 0 (from extended neglect), it dies. But it leaves behind an egg that hatches into a new creature with a small XP bonus based on its parent's level. Your lineage is tracked — run `/tamagotchi history` to see all past generations.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `/tamagotchi` | View creature stats, HP, XP, streak, and lineage |\n| `/tamagotchi setup` | Auto-integrate with your status line script |\n| `/tamagotchi rename <name>` | Rename your creature |\n| `/tamagotchi theme` | Browse themes and set preference for next hatch |\n| `/tamagotchi history` | Full lineage across all generations |\n\n## Custom Themes\n\nCreate your own theme by adding a JSON file to `~/.claude/tamagotchi/themes/`:\n\n```json\n{\n  \"name\": \"ocean\",\n  \"emoji\": [\"🥚\", \"🐚\", \"🦐\", \"🐠\", \"🐋\"],\n  \"levels\": [1, 2, 3, 4, 5]\n}\n```\n\nThe first emoji should always be `🥚` to preserve the surprise on hatch.\n\n## How State Works\n\nAll creature state lives in `~/.claude/tamagotchi/state.json`, outside the plugin cache. This means:\n\n- State survives plugin updates and reinstalls\n- Uninstalling the plugin stops the hooks but doesn't delete your creature\n- The status line reads a pre-rendered `display.txt` file for near-zero overhead\n\n## Uninstall\n\n```bash\n/plugin uninstall claude-tamagotchi\n```\n\nThen remove the Tamagotchi lines from your `~/.claude/statusline-command.sh`. Optionally delete `~/.claude/tamagotchi/` to remove all creature state.\n",
  "bytes": 3659,
  "sha": "08a988ba570498dadf195ac02170ab29fcd6ecc7b04ebd9f157610260e92ead5",
  "repo_slug": "ncrohn/claude-tamagotchi",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_ncrohn_claude_tamagotchi_claude_tamagotc_040ea7da/readme"
}