Critter: A virtual pet for your terminal

Tue, 13 Oct 2026 00:00:00 +0000

I recently bought one of these retro Tamagotchi devices. For fun, I made a CLI/browser toy that's very similar. Go ahead and use the buttons to feed the hungry Critter. But it works best when installed as a CLI tool.

Context
Usage
Integrations
- Short output
- JSON output
Automated tests

Context

Here's the Tamagotchi I recently bought. It's a reproduction, not an original.

Usage

You can find installation instructions in the repository. After installation, create your critter with critter new.

$ critter new

⠀⠀⠀⠀⠀▄▀▀▀▄
⠀⠀⠀⠀▄▀▄⠀⠀▀▄
⠀⠀⠀▄▀⠀⠀⠀▀⠀▀▄
⠀⠀⠀▀▄⠀▀⠀▄⠀▄▀
⠀⠀⠀⠀▀▄▄▄▄▄▀

A 0 seconds

After a couple of minutes, it will hatch. Check the status with just critter. It'll probably be hungry. Feed it with critter feed.

critter --help will show you all the commands. This project works best with a Nerd Font. If you don't have one installed, pass the -n flag to use the fallback text string instead of icons.

Integrations

Short output

Looking to integrate it into your status bar or similar? Try critter -s.

$ critter -s
ʕ•ᴥ•ʔ H▇ S▂ E▇ +█ T▂

JSON output

For more advanced integrations, call critter -j. It gives you all sorts of information for more advanced use cases.

$ critter -j
{
  "action": "idle",
  "actionTime": 0,
  "alert": false,
  "Bars": "󰱱▇ 󰉛▂ 󱊣▇ █ 󰦫▂",
  "Bars-nonerd": "H▇ S▂ E▇ +█ T▂",
  "emoticon": "ʕ•ᴥ•ʔ",
  "emoticon-nonerd": "ʕ•ᴥ•ʔ",
  "Energy": 744064,
  "Happy": 690411,
  "Health": 1000000,
  "Hunger": 298092,
  "plain": "█▀█▄▄▄█▀█\n█       █\n█ █   █ █▄▄▄▄▄▄\n█   ▄   █     ██\n█▄▄▄▄▄▄▄█     █\n █            █\n █  █▀█  █▀▀█ █\n █▄▄█ █▄▄█  █▄█\n\nIDLE\n󰱱 󰋑󰋑󰋑󰛞󰋕  󰉛 󰋑󰛞󰋕󰋕󰋕\n󱊣 󰋑󰋑󰋑󰛞󰋕   󰋑󰋑󰋑󰋑󰋑\n󰦫 󰋑󰋕󰋕󰋕󰋕  󰥔 2 days",
  "plain-nonerd": "█▀█▄▄▄█▀█\n█       █\n█ █   █ █▄▄▄▄▄▄\n█   ▄   █     ██\n█▄▄▄▄▄▄▄█     █\n █            █\n █  █▀█  █▀▀█ █\n █▄▄█ █▄▄█  █▄█\n\nIDLE\nH │███▌ │  S │█▌   │\nE │███▌ │  + │█████│\nT │█    │  A 2 days",
  "plainSprites": "█▀█▄▄▄█▀█\n█       █\n█ █   █ █▄▄▄▄▄▄\n█   ▄   █     ██\n█▄▄▄▄▄▄▄█     █\n █            █\n █  █▀█  █▀▀█ █\n █▄▄█ █▄▄█  █▄█",
  "plainStats": "IDLE\n󰱱 󰋑󰋑󰋑󰛞󰋕  󰉛 󰋑󰛞󰋕󰋕󰋕\n󱊣 󰋑󰋑󰋑󰛞󰋕   󰋑󰋑󰋑󰋑󰋑\n󰦫 󰋑󰋕󰋕󰋕󰋕  󰥔 2 days",
  "plainStats-nonerd": "IDLE\nH │███▌ │  S │█▌   │\nE │███▌ │  + │█████│\nT │█    │  A 2 days",
  "poo": false,
  "short": "ʕ•ᴥ•ʔ 󰱱▇ 󰉛▂ 󱊣▇ █ 󰦫▂",
  "short-nonerd": "ʕ•ᴥ•ʔ H▇ S▂ E▇ +█ T▂",
  "Toilet": 183458
}

Want to know when your critter is hungry, sad, soiled, etc.? Periodically check the alert property.

$ critter -j | jq .alert
true

After reading an alert, call critter dismiss to clear it.

For example, a cron job or integration should call critter dismiss after sending the notification.

Automated tests

One of the cool things about the project are the automated tests. With them dozens of critters are simulated to see how long they survive in certain conditions. Though I still grapple with the moral implication of spawning dozens of critters only to let them automatically die. It's probably fine.

 > dies within the configured low-happiness health schedule
Critter died after 5 days, 18 hours, 53 minutes, 20 seconds (500000 seconds total).

 > dies within the configured zero-happiness health schedule
Critter died after 2 days, 21 hours, 26 minutes, 40 seconds (250000 seconds total).

 > dies within a week with only six-hour meals shifted by -60 minutes
Critter died after 2 days, 9 hours, 5 minutes, 0 seconds (205500 seconds total).

 > dies within a week with only six-hour meals shifted by -30 minutes
Critter died after 2 days, 5 hours, 46 minutes, 0 seconds (193560 seconds total).

 > dies within a week with only six-hour meals shifted by 30 minutes
Critter died after 2 days, 6 hours, 35 minutes, 0 seconds (196500 seconds total).

 > dies within a week with only six-hour meals shifted by 60 minutes
Critter died after 2 days, 7 hours, 0 minutes, 0 seconds (198000 seconds total).

 > dies within five days without commanded sleep despite feeding and cleaning
Critter died after 2 days, 11 hours, 41 minutes, 0 seconds (214860 seconds total).

 > loses more health when poo cleaning is delayed
Critter died after 2 days, 3 hours, 49 minutes, 0 seconds (186540 seconds total).
Critter died after 1 days, 11 hours, 8 minutes, 0 seconds (126480 seconds total).
Critter died after 1 days, 6 hours, 18 minutes, 0 seconds (109080 seconds total).

 > is dead by thirty days when only fed daily and poo is cleaned
Critter died after 1 days, 11 hours, 32 minutes, 0 seconds (127920 seconds total).

 > is dead by thirty days when fed every five hours and poo is left
Critter died after 1 days, 6 hours, 18 minutes, 0 seconds (109080 seconds total).

 > survives one day but dies within two when neglected from full health
Critter died after 1 days, 8 hours, 56 minutes, 0 seconds (118560 seconds total).

 > hatches before dying within two days when neglected from birth

glow.li: 2026