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. The desktop info strip shows the next bedtime, and bedtime starts with a lights-off warning. |
| 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: bedtime/lights, sickness, poop, or discipline. 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. When bedtime hits, you have a 15-minute window to turn the lights off. Once the pet is asleep, decay pauses. At wake time, age increments by 1.
That wake-time age increase is what moves the pet toward later stages, so bedtime matters for evolution as well as care.
The desktop app shows bedtime cues in the info strip below the LCD, including the next bedtime and active lights deadlines. The TUI shows BEDTIME in the status/help line when lights need attention.
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. When bedtime starts, the status area shows BEDTIME so you know to press l.
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 |