cli-tamagotchi 1.0.0__tar.gz

cli_tamagotchi-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eneko Galan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cli_tamagotchi-1.0.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: cli-tamagotchi
+Version: 1.0.0
+Summary: A terminal Tamagotchi that reacts to your care.
+Author: Eneko Galan Elorza
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/enegalan/cli-tamagotchi
+Project-URL: Repository, https://github.com/enegalan/cli-tamagotchi.git
+Project-URL: Issues, https://github.com/enegalan/cli-tamagotchi/issues
+Project-URL: Changelog, https://github.com/enegalan/cli-tamagotchi/releases
+Keywords: cli,game,tamagotchi,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich
+Provides-Extra: claude-code
+Provides-Extra: agents
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# cli-tamagotchi
+
+`cli-tamagotchi` is a terminal-first Tamagotchi. It gives you one persistent pet, keeps aging it while the CLI is closed, and lets you care for it with a small `tama` command set.
+
+## Features
+
+- **One active pet** in `~/.cli-tamagotchi/pet.json` (override the data directory with `CLI_TAMAGOTCHI_HOME`)
+- **Graveyard** for past pets in `~/.cli-tamagotchi/graveyard.json`
+- **Stats:** hunger, happiness, health, weight, energy, dirtiness; wake/sleep; optional illnesses
+- **Life stages:** Egg → Baby → Child → Adult (time-based growth), with death when care or health fails
+- **Offline decay** reconciled from elapsed real time whenever you run a command
+- **Care actions:** feed, play, lights on/off, clean, medicine (one-hour cooldown; helps cure illness)
+- **Event log** stored with the pet state (trimmed to the most recent entries)
+- **ASCII sprites** with mood and stage-aware animation in the UI
+- **CLI subcommands** for quick actions, plus **`tama` alone** for the interactive loop
+- **Plugin system** with lifecycle hooks (`on_tick`, `on_event`, `on_action`, `on_external_event`, ...)
+
+## Requirements
+
+- Python **3.9+**
+
+## Install and run
+
+```bash
+pip install cli-tamagotchi
+```
+
+Editable install from a clone:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+### CLI (`tama`)
+
+```bash
+tama status
+tama feed
+tama play
+tama lights
+tama clean
+tama medicine
+tama logs
+tama new          # only when no living pet
+tama graveyard
+tama plugin emit my_event --data '{"k":"v"}'   # notify all plugins
+tama              # interactive UI
+```
+
+Plugins are loaded when `tama` starts. To pick up plugin code changes, restart the command.
+
+Setup details: [integrations/README.md](integrations/README.md).
+
+Run without installing the console script:
+
+```bash
+PYTHONPATH=src:plugins python3 -m cli_tamagotchi status
+```
+
+Use `tama -h` for built-in help on subcommands.
+
+## Interactive mode
+
+Running `tama` with no arguments starts the main UI: status, animated pet, stat bars, and an action grid. On a proper TTY, navigation uses single-key input; otherwise a simple line-based fallback is used.
+
+While your pet is alive you can use feed, play, lights, clean, medicine, open the **graveyard** view, or quit. After death you can start a **new pet** (when allowed) or browse the graveyard. The event log can be scrolled when shown in the interactive layout.
+
+## Persistence
+
+State lives under `~/.cli-tamagotchi/` by default (or under `CLI_TAMAGOTCHI_HOME` if set). The save includes name, character, stage, weight, stats, sleep and dirtiness, illness and medicine timestamps, timestamps for creation/updates/ticks/interactions, and the recent event log. Offline progression runs from the last processed tick when any command loads the pet.
+
+## Tests
+
+```bash
+python3 -m pytest tests/
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

cli_tamagotchi-1.0.0/README.md

@@ -0,0 +1,86 @@
+# cli-tamagotchi
+
+`cli-tamagotchi` is a terminal-first Tamagotchi. It gives you one persistent pet, keeps aging it while the CLI is closed, and lets you care for it with a small `tama` command set.
+
+## Features
+
+- **One active pet** in `~/.cli-tamagotchi/pet.json` (override the data directory with `CLI_TAMAGOTCHI_HOME`)
+- **Graveyard** for past pets in `~/.cli-tamagotchi/graveyard.json`
+- **Stats:** hunger, happiness, health, weight, energy, dirtiness; wake/sleep; optional illnesses
+- **Life stages:** Egg → Baby → Child → Adult (time-based growth), with death when care or health fails
+- **Offline decay** reconciled from elapsed real time whenever you run a command
+- **Care actions:** feed, play, lights on/off, clean, medicine (one-hour cooldown; helps cure illness)
+- **Event log** stored with the pet state (trimmed to the most recent entries)
+- **ASCII sprites** with mood and stage-aware animation in the UI
+- **CLI subcommands** for quick actions, plus **`tama` alone** for the interactive loop
+- **Plugin system** with lifecycle hooks (`on_tick`, `on_event`, `on_action`, `on_external_event`, ...)
+
+## Requirements
+
+- Python **3.9+**
+
+## Install and run
+
+```bash
+pip install cli-tamagotchi
+```
+
+Editable install from a clone:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+### CLI (`tama`)
+
+```bash
+tama status
+tama feed
+tama play
+tama lights
+tama clean
+tama medicine
+tama logs
+tama new          # only when no living pet
+tama graveyard
+tama plugin emit my_event --data '{"k":"v"}'   # notify all plugins
+tama              # interactive UI
+```
+
+Plugins are loaded when `tama` starts. To pick up plugin code changes, restart the command.
+
+Setup details: [integrations/README.md](integrations/README.md).
+
+Run without installing the console script:
+
+```bash
+PYTHONPATH=src:plugins python3 -m cli_tamagotchi status
+```
+
+Use `tama -h` for built-in help on subcommands.
+
+## Interactive mode
+
+Running `tama` with no arguments starts the main UI: status, animated pet, stat bars, and an action grid. On a proper TTY, navigation uses single-key input; otherwise a simple line-based fallback is used.
+
+While your pet is alive you can use feed, play, lights, clean, medicine, open the **graveyard** view, or quit. After death you can start a **new pet** (when allowed) or browse the graveyard. The event log can be scrolled when shown in the interactive layout.
+
+## Persistence
+
+State lives under `~/.cli-tamagotchi/` by default (or under `CLI_TAMAGOTCHI_HOME` if set). The save includes name, character, stage, weight, stats, sleep and dirtiness, illness and medicine timestamps, timestamps for creation/updates/ticks/interactions, and the recent event log. Offline progression runs from the last processed tick when any command loads the pet.
+
+## Tests
+
+```bash
+python3 -m pytest tests/
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

cli_tamagotchi-1.0.0/plugins/claude_code/__init__.py

@@ -0,0 +1,3 @@
+from .plugin import ClaudeCodePlugin
+
+__all__ = ("ClaudeCodePlugin",)

cli_tamagotchi-1.0.0/plugins/claude_code/plugin.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import json
+import time
+from collections import Counter, deque
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from cli_tamagotchi.models import PetState, clamp_stat
+from cli_tamagotchi.plugins.base import BasePlugin
+
+
+class AgentBehaviorClassifier:
+    WINDOW = 20
+
+    def __init__(self) -> None:
+        self._tool_calls: deque[dict[str, Any]] = deque(maxlen=self.WINDOW)
+        self._last_write_at: float = 0.0
+        self._error_count = 0
+        self._loop_counter: Counter[str] = Counter()
+
+    def record_tool_call(self, tool: str, exit_code: int = 0) -> str:
+        now = time.time()
+        self._tool_calls.append({"tool": tool, "ts": now, "exit": exit_code})
+        self._loop_counter[tool] += 1
+
+        if tool in ("write_file", "edit_file", "bash") and exit_code == 0:
+            self._last_write_at = now
+            self._loop_counter.clear()
+
+        if exit_code != 0:
+            self._error_count += 1
+        else:
+            self._error_count = max(0, self._error_count - 1)
+
+        return self.classify()
+
+    def classify(self) -> str:
+        if self._error_count >= 5:
+            return "BLOCKED"
+        if any(count >= 5 for count in self._loop_counter.values()):
+            return "LOOPING"
+        recent_tools = [e["tool"] for e in self._tool_calls]
+        write_tools = {"write_file", "edit_file", "bash", "str_replace_editor"}
+        read_tools = {"read_file", "list_dir", "grep", "glob"}
+        writes = sum(1 for t in recent_tools if t in write_tools)
+        reads = sum(1 for t in recent_tools if t in read_tools)
+        if writes > reads:
+            return "SHIPPING"
+        if reads > 5 and writes == 0:
+            return "EXPLORING"
+        return "WORKING"
+
+
+BEHAVIOR_REACTIONS: dict[str, dict[str, int]] = {
+    "SHIPPING": {"happy_delta": 1, "hunger_delta": 0},
+    "LOOPING": {"happy_delta": -1, "hunger_delta": -1},
+    "EXPLORING": {"happy_delta": 0, "hunger_delta": 0},
+    "BLOCKED": {"happy_delta": -1, "hunger_delta": -1},
+    "WORKING": {"happy_delta": 0, "hunger_delta": 0},
+    "DONE_SUCCESS": {"happy_delta": 2, "hunger_delta": 1},
+    "DONE_FAILURE": {"happy_delta": -1, "hunger_delta": -1},
+    "TESTS_PASSED": {"happy_delta": 2, "hunger_delta": 1},
+    "TESTS_FAILED": {"happy_delta": -1, "hunger_delta": 0},
+}
+
+
+def _apply_reaction(pet_state: PetState, key: str) -> None:
+    reaction = BEHAVIOR_REACTIONS.get(key, BEHAVIOR_REACTIONS["WORKING"])
+    pet_state.happiness = clamp_stat(pet_state.happiness + reaction["happy_delta"] * 15)
+    pet_state.hunger = clamp_stat(pet_state.hunger + reaction["hunger_delta"] * 12)
+
+
+class ClaudeCodePlugin(BasePlugin):
+    name = "claude_code"
+    description = "Reacts to Claude Code agent behavior"
+    version = "0.1.0"
+    events_jsonl_basename = "claude_events.jsonl"
+
+    def __init__(self) -> None:
+        self._classifier = AgentBehaviorClassifier()
+        self._last_event_line = 0
+        self._last_behavior = "WORKING"
+        self._behavior_tick = 0
+
+    def _event_path(self) -> Path:
+        path = self.events_jsonl_path()
+        if path is None:
+            raise RuntimeError("ClaudeCodePlugin.events_jsonl_basename must be set")
+        return path
+
+    def on_load(self) -> None:
+        path = self._event_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if not path.exists():
+            path.touch()
+
+    def on_tick(self, pet_state: PetState, tick_time: datetime) -> None:
+        self._poll_events(pet_state)
+        self._behavior_tick += 1
+        if self._behavior_tick % 60 == 0:
+            _apply_reaction(pet_state, self._last_behavior)
+
+    def _poll_events(self, pet_state: PetState) -> None:
+        path = self._event_path()
+        if not path.exists():
+            return
+        lines = path.read_text(encoding="utf-8").splitlines()
+        new_lines = lines[self._last_event_line :]
+        self._last_event_line = len(lines)
+
+        for line in new_lines:
+            try:
+                event = json.loads(line)
+                self._process_event(pet_state, event)
+            except (json.JSONDecodeError, TypeError, ValueError, KeyError):
+                pass
+
+    def _process_event(self, pet_state: PetState, event: dict[str, Any]) -> None:
+        etype = event.get("type", "")
+        if etype == "pre_tool":
+            return
+        if etype == "post_tool":
+            tool = event.get("tool", "unknown")
+            exit_code = int(event.get("exit_code", 0))
+            behavior = self._classifier.record_tool_call(tool, exit_code)
+            self._last_behavior = behavior
+            if tool == "bash" and "pytest" in event.get("command", ""):
+                if exit_code == 0:
+                    _apply_reaction(pet_state, "TESTS_PASSED")
+                else:
+                    _apply_reaction(pet_state, "TESTS_FAILED")
+        elif etype == "stop":
+            reason = event.get("reason", "")
+            if reason in ("task_complete", "success"):
+                _apply_reaction(pet_state, "DONE_SUCCESS")
+            else:
+                _apply_reaction(pet_state, "DONE_FAILURE")
+        elif etype == "subagent_start":
+            pet_state.happiness = clamp_stat(pet_state.happiness - 12)
+
+    def on_external_event(self, event_type: str, data: dict[str, Any]) -> None:
+        pass
+
+
+def build_hook_event(args: list[str]) -> tuple[Path, dict[str, object]] | None:
+    """Parse ``tama-hook`` argv for Claude Code; return None if these are not Claude commands."""
+    if not args:
+        return None
+
+    payload: dict[str, object] = {"ts": time.time()}
+    command = args[0]
+
+    if command == "pre-tool" and len(args) >= 2:
+        payload.update({"type": "pre_tool", "tool": args[1]})
+    elif command == "post-tool" and len(args) >= 3:
+        payload.update(
+            {
+                "type": "post_tool",
+                "tool": args[1],
+                "exit_code": int(args[2]),
+                "command": " ".join(args[3:]) if len(args) > 3 else "",
+            }
+        )
+    elif command == "stop" and len(args) >= 2:
+        payload.update({"type": "stop", "reason": args[1]})
+    elif command == "subagent-start":
+        payload.update({"type": "subagent_start"})
+    else:
+        return None
+
+    path = ClaudeCodePlugin.events_jsonl_path()
+    if path is None:
+        return None
+    return (path, payload)

cli_tamagotchi-1.0.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cli-tamagotchi"
+version = "1.0.0"
+description = "A terminal Tamagotchi that reacts to your care."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+    { name = "Eneko Galan Elorza" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["cli", "game", "tamagotchi", "terminal"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Games/Entertainment",
+]
+dependencies = [
+    "rich",
+]
+
+[project.urls]
+Homepage = "https://github.com/enegalan/cli-tamagotchi"
+Repository = "https://github.com/enegalan/cli-tamagotchi.git"
+Issues = "https://github.com/enegalan/cli-tamagotchi/issues"
+Changelog = "https://github.com/enegalan/cli-tamagotchi/releases"
+
+[project.optional-dependencies]
+claude-code = []
+agents = []
+dev = [
+    "build>=1.2",
+    "twine>=5",
+    "pytest>=7",
+]
+
+[project.scripts]
+tama = "cli_tamagotchi.cli:main"
+tama-hook = "cli_tamagotchi.plugins.hooks:tama_hook_main"
+
+[project.entry-points."cli_tamagotchi.plugins"]
+claude_code = "claude_code.plugin:ClaudeCodePlugin"
+
+[project.entry-points."cli_tamagotchi.hook_builders"]
+claude_code = "claude_code.plugin:build_hook_event"
+
+[tool.setuptools]
+package-dir = {
+    "" = "src",
+    "claude_code" = "plugins/claude_code",
+}
+
+[tool.setuptools.packages.find]
+where = ["src", "plugins"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src", "plugins"]
+testpaths = ["tests"]

cli_tamagotchi-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cli_tamagotchi-1.0.0/setup.py

@@ -0,0 +1,5 @@
+"""Compatibility shim for editable installs with older pip versions."""
+
+from setuptools import setup
+
+setup()

cli_tamagotchi-1.0.0/src/cli_tamagotchi/__init__.py

@@ -0,0 +1,5 @@
+"""cli-tamagotchi package."""
+
+from .cli import main
+
+__all__ = ["main"]

cli_tamagotchi-1.0.0/src/cli_tamagotchi/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cli_tamagotchi-1.0.0/src/cli_tamagotchi/characters.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+from enum import Enum
+
+FALLBACK_CHARACTER = "Cat"
+
+
+class Rarity(str, Enum):
+    COMMON = "common"
+    UNCOMMON = "uncommon"
+    RARE = "rare"
+    EPIC = "epic"
+    LEGENDARY = "legendary"
+
+
+RARITY_DISPLAY = {
+    Rarity.COMMON: "Common",
+    Rarity.UNCOMMON: "Uncommon",
+    Rarity.RARE: "Rare",
+    Rarity.EPIC: "Epic",
+    Rarity.LEGENDARY: "Legendary",
+}
+
+
+@dataclass(frozen=True)
+class CharacterSpec:
+    character_id: str
+    rarity: Rarity
+    roll_weight: int
+    rich_style: str
+    healthy_weight_min: int
+    healthy_weight_max: int
+
+
+CHARACTER_POOL: tuple[CharacterSpec, ...] = (
+    CharacterSpec(
+        character_id="Cat",
+        rarity=Rarity.COMMON,
+        roll_weight=48,
+        rich_style="bright_cyan",
+        healthy_weight_min=3,
+        healthy_weight_max=26,
+    ),
+    CharacterSpec(
+        character_id="Dog",
+        rarity=Rarity.UNCOMMON,
+        roll_weight=25,
+        rich_style="bright_yellow",
+        healthy_weight_min=3,
+        healthy_weight_max=24,
+    ),
+    CharacterSpec(
+        character_id="Fox",
+        rarity=Rarity.RARE,
+        roll_weight=17,
+        rich_style="bright_magenta",
+        healthy_weight_min=2,
+        healthy_weight_max=20,
+    ),
+    CharacterSpec(
+        character_id="Owl",
+        rarity=Rarity.EPIC,
+        roll_weight=10,
+        rich_style="bright_blue",
+        healthy_weight_min=2,
+        healthy_weight_max=18,
+    ),
+)
+
+_CHARACTER_RARITY: dict[str, Rarity] = {spec.character_id: spec.rarity for spec in CHARACTER_POOL}
+_CHARACTER_WEIGHTS: tuple[tuple[str, int], ...] = tuple(
+    (spec.character_id, spec.roll_weight) for spec in CHARACTER_POOL
+)
+
+CHARACTER_STYLE_BY_NAME: dict[str, str] = {spec.character_id: spec.rich_style for spec in CHARACTER_POOL}
+
+
+def healthy_weight_bounds(character_id: str) -> tuple[int, int]:
+    for spec in CHARACTER_POOL:
+        if spec.character_id == character_id:
+            return (spec.healthy_weight_min, spec.healthy_weight_max)
+    return (3, 26)
+
+
+def rarity_for_character(character_id: str) -> Rarity:
+    return _CHARACTER_RARITY.get(character_id, Rarity.COMMON)
+
+
+def rarity_display_for_character(character_id: str) -> str:
+    return RARITY_DISPLAY[rarity_for_character(character_id)]
+
+
+def character_status_label(character_id: str) -> str:
+    return f"{character_id} ({rarity_display_for_character(character_id)})"
+
+
+def roll_starting_character(rng: random.Random | None = None) -> str:
+    random_source = rng if rng is not None else random.Random()
+    character_ids = [pair[0] for pair in _CHARACTER_WEIGHTS]
+    weights = [pair[1] for pair in _CHARACTER_WEIGHTS]
+    chosen = random_source.choices(character_ids, weights=weights, k=1)[0]
+    return chosen