Docs
How it works
Your pet lives in real time. Every minute the simulation ticks. Hunger and happiness decay, poop accumulates, sickness can set in. One real day equals one pet year. Leave your pet alone too long and it dies. Take good care of it and it evolves into a better character.
LCD icons
The LCD screen has two rows of icons you can click (or use keyboard shortcuts in the TUI).
Top row
| Icon | Name | What it does |
|---|---|---|
| Fork/knife | Feed | Meal restores 1 hunger (+1 weight). Snack restores 1 happiness (+2 weight). Can't feed a sick pet. |
| Diamond | Light | Toggle lights. Turn off at bedtime so your pet can sleep. |
| Ball | Game | 5-round guessing game. Win 3+ to gain 1 happiness. Burns 1 weight. |
| Cross | Medicine | 2 doses to cure sickness. Only works when sick. |
Bottom row
| Icon | Name | What it does |
|---|---|---|
| Bathtub | Clean | Removes one poop. 4+ poops makes your pet sick. |
| Meter | Stats | Shows hunger, happiness, weight. Info only. |
| Person | Discipline | Scold when a discipline call appears (~10% chance per tick, 15min deadline). |
| ! | Attention | Shows what needs attention. Info only. |
Meters
Hunger and happiness each have 4 hearts. They decay at rates that depend on your character. When either hits 0, a 15-minute care deadline starts. Miss it and you get a care mistake.
Discipline is 0-100%. Goes up 25% each time you successfully discipline.
Sickness
Your pet gets sick from too much poop (4+) or overfeeding snacks as a baby (3+). A sick pet can't eat or play. Give 2 doses of medicine to cure it.
Death
Your pet can die from old age, neglect (hunger AND happiness at 0 for 12+ hours), untreated sickness, or baby snack overfeeding (5+). Hatch a new egg from the death screen.
Sleep
Each character has a bedtime and wake time. Turn lights off at bedtime. At wake time, age increments by 1.
Evolution
Egg (5min) → Babytchi (65min) → Marutchi (age 3) → Teen (age 6) → Adult Teen: care_mistakes 0-2 → Tamatchi, 3+ → Kuchitamatchi Adult: full P1 matrix based on teen char, type, care + discipline mistakes Best care → Mametchi · Worst care → Tarakotchi Special: Maskutchi (Tamatchi T2 path) after 4 days → Oyajitchi
MCP / AI agent
The desktop app bundles an MCP server that AI tools can connect to. Open settings in the app and click "Copy to clipboard" to get the config for your AI tool.
Agent permissions are configurable per-action with rate limits. The master switch disables all agent access.
TUI keyboard shortcuts
| Key | Action |
|---|---|
f | Feed (then m for meal, s for snack) |
g | Play game |
d | Discipline |
c | Clean poop |
l | Toggle lights |
i | Give medicine |
a | About |
q | Quit |
If the desktop app is running, the TUI enters client mode automatically.
Data directory
Everything lives in ~/.tama96/
| File | Purpose |
|---|---|
state.json | Pet state |
permissions.json | Agent permission config |
mcp_config.json | Ready-to-copy MCP config |
mcp_port | TCP port for MCP bridge |
tama96.lock | Single-instance lockfile |