tamaterm

A virtual pet that lives in your terminal.

┌────────────────────────┐
│ ★ Whiskers [adult]     │
│    /\_____/\           │
│   /  *   *  \          │
│  ( ==  w  == )         │
│   )    ♪    (          │
│  (           )         │
│  hunger  [████████████░░]  85.0 │
│  happy   [██████████████]  92.0 │
│  energy  [████████░░░░░░]  55.0 │
│  clean   [██████████░░░░]  70.0 │
└────────────────────────┘

What is this?

tamaterm is a Tamagotchi-style virtual pet that lives in your terminal prompt. It reacts to your developer workflow -- git commits make it happy, CPU spikes stress it out, and it grows through life stages the longer you care for it.

It's not a TUI app. It lives in your prompt, above every command you type.

Install

pip install tamaterm

Quick Start

# Create your pet
tamaterm init Whiskers --type cat

# Install the shell hook (adds pet above your prompt)
tamaterm install

# Restart your terminal, then care for your pet
tamaterm feed
tamaterm play
tamaterm clean

How it works

Background daemon (tamaterm daemon)
├── Monitors: git status, CPU, memory, time
├── Updates: ~/.tamaterm/pet.json (state)
└── Writes: ~/.tamaterm/status.txt (display)

Shell hook (in your .bashrc/.zshrc/profile)
└── cat ~/.tamaterm/status.txt before prompt

CLI (tamaterm feed/play/clean/sleep)
└── Modifies pet.json, daemon picks up changes

Features

• Growth system: Egg -> Baby -> Teen -> Adult (care-dependent)
• Reactive: Happy when you commit code, stressed during CPU spikes
• Stat decay: Hunger, happiness, energy, hygiene decay over time
• Night mode: Pet sleeps automatically at night
• Multi-shell: Bash, Zsh, PowerShell, Fish
• Cross-platform: Linux, macOS, Windows
• Lightweight: 2 dependencies (click, psutil), ~50KB installed

Pet Types

Commands

How the pet reacts

Development

# Clone and install in dev mode
git clone https://github.com/violet2314275/tamaterm.git
cd tamaterm
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# Lint
ruff check src/ tests/

# Build package
python -m build

Contributing

Add a new pet! Create a file in src/tamaterm/art/ with ASCII art for each stage and mood. See art/cat.py for the pattern.

Each pet needs art for these moods at each stage (egg, baby, teen, adult): NORMAL, HAPPY, HUNGRY, SAD, SLEEPING, DEAD.

License

MIT