terminal-pet

A little animated Tamagotchi-like companion that lives on top of your terminal window and reacts to what you do in the shell.

• Sits in the corner of whichever terminal window is in front (or perched on its title bar, if you prefer), and follows it when you move or resize it.
• Hides when the terminal isn't the active app, so it never gets in the way.
• Watches your zsh session: working while a command runs, happy when it succeeds, sad when it fails, sleeping when you've been away for a while.
• Is a little Tamagotchi: it gets hungry over the day and asks for food, gains xp and levels from the commands you run, keeps streaks of successful commands, and talks in a speech bubble. Click it or pet feed it.
• Fully customisable: drop in your own animated GIFs (or APNGs) for each state, or point it at a single GIF and it'll just loop that.

macOS only for now (native Swift/AppKit, no dependencies). Linux and Windows are on the roadmap.

Install

Requires macOS 13 or later. Works with zsh, bash and fish.

Homebrew

brew install Zezoo123/tap/terminal-pet
terminal-pet setup

From source (needs the Xcode Command Line Tools, xcode-select --install)

git clone https://github.com/Zezoo123/terminal-pet.git
cd terminal-pet
make install            # builds and installs to ~/.local (override with PREFIX=/usr/local)
~/.local/bin/terminal-pet setup

setup detects your shell from $SHELL, adds the matching plugin to its startup file, and puts terminal-pet on your PATH if it isn't already (--shell bash to pick explicitly, --print to only show the lines). Then open a new terminal and start the pet:

terminal-pet            # detaches and gives you the prompt back; `make launchd` starts it at login
terminal-pet stop       # when you've had enough

Run any command and watch it react.

Doing it by hand instead of setup

shell	add to	line
zsh	~/.zshrc	source ~/.local/share/terminal-pet/terminal-pet.plugin.zsh
bash	~/.bash_profile (or ~/.bashrc)	source ~/.local/share/terminal-pet/terminal-pet.plugin.bash
fish	~/.config/fish/conf.d/terminal-pet.fish	source ~/.local/share/terminal-pet/terminal-pet.fish

And export PATH="$HOME/.local/bin:$PATH" (fish_add_path ~/.local/bin in fish) if ~/.local/bin isn't on your PATH. With Homebrew the files live under $(brew --prefix)/opt/terminal-pet/share/terminal-pet/ instead.

zsh plugin managers can load the plugin straight from the repo (the app still has to be installed): zinit light Zezoo123/terminal-pet, antigen bundle Zezoo123/terminal-pet, or clone it into $ZSH_CUSTOM/plugins/terminal-pet for oh-my-zsh.

Try it without installing

make run                # runs in the foreground with the repo's pets, Ctrl-C to quit

Shell integration

Each plugin hooks the shell's "command is about to run" and "prompt is about to show" events and sends one line over a Unix socket (/tmp/terminal-pet-<uid>.sock). It is a no-op when the pet isn't running.

It also gives you a pet command:

pet            # poke it
pet feed       # feed it
pet stats      # level, xp, hunger, streaks, age
pet say hi     # speech bubble (try it at the end of a long script)
pet name Bob   # give it a name
pet ghost      # switch to another pet (any name from `pet list`, a folder, or a .gif)
pet sad        # force a state: idle | working | happy | sad | sleeping | eating | hungry | celebrate | pushing | scared
pet scale 4    # resize
pet anchor inside-bottom-left
pet list       # what's installed
pet status
pet quit

Caring for it

Everything is kept in ~/.config/terminal-pet/stats.json. Delete it to start over.

It knows what you're running

The pet reads the command line and reacts to the ones that matter:

The full list is in Reactions.swift. Add your own in the config; they're checked before the built-in ones, first match wins, patterns are case-insensitive regular expressions matched against the command line:

{
  "reactions": [
    { "match": "^deploy\\b",
      "start":   { "state": "scared",    "say": "deploying..." },
      "success": { "state": "celebrate", "say": "live!" },
      "failure": { "state": "sad",       "say": "rollback?" } },
    { "match": "^make coffee", "success": { "say": "finally" } }
  ]
}

Each of start, success, failure is optional, and so are state and say inside them. States: idle, working, happy, sad, sleeping, eating, hungry, celebrate, pushing, scared.

Changing things on the fly

While a pet is running, the CLI talks to it instead of starting another one, and every change is written to the config file so it sticks:

terminal-pet --pet ghost                 # ok now showing Ghost (saved to config)
terminal-pet --scale 4
terminal-pet --anchor top-right
terminal-pet status                      # pet=Ghost state=idle anchor=top-right scale=4.0 ...

The same flags with no pet running start one with those settings.

Anything else can send raw events with terminal-pet send <event>, e.g. from a Makefile, a CI script, or bash:

terminal-pet send preexec make
terminal-pet send precmd 1      # exit status

Bundled pets

Pick one with "pet": "cat" in the config or terminal-pet --pet cat. terminal-pet pets lists everything installed.

Configuration

~/.config/terminal-pet/config.json (created by make install, every key optional):

Flags override the file for one run: terminal-pet --pet ~/Downloads/cat.gif --scale 1 --anchor top-right.

Making your own pet

A pet is a folder with one animated image per state: idle, working, happy, sad, sleeping, eating, hungry, celebrate, pushing, scared. Missing states fall back sensibly (eating and celebrate to happy, pushing and scared to working, everything else to idle), so a single idle.gif is enough.

~/.config/terminal-pet/pets/cat/
├── pet.json      (optional)
├── idle.gif
├── working.gif
├── happy.gif
├── sad.gif
├── sleeping.gif
└── eating.gif

pet.json lets you name it and use different file names:

{ "name": "Cat", "states": { "idle": "sit.gif", "working": "typing.gif" } }

GIF and APNG are both supported and per-frame delays are respected. Pixel art is drawn with nearest-neighbour scaling, so a 24x24 sprite at scale: 3 is crisp. terminal-pet pets lists everything it can find. Pets are searched in $TERMINAL_PET_PETS_DIR, ~/.config/terminal-pet/pets, then the installed share directory.

The bundled pets are all generated from scripts/gen-pets.swift: each one is a small ASCII-art body plus shared helpers for eyes, mouths, tears and Zs. make pets regenerates them and writes a contact sheet to .build/pets-sheet.png. Copy one of the func cat()-style definitions to make a new character. make demo re-records the README demo from a real Terminal window (asks for Screen Recording permission once; no ffmpeg needed).

How it works

• Sources/terminal-pet/TerminalTracker.swift finds the frontmost terminal window through CGWindowListCopyWindowInfo. Window bounds aren't permission-gated, so no Accessibility or Screen Recording prompts.
• PetPanel.swift is a borderless, transparent, non-activating NSPanel at floating level. Clicking it never steals focus.
• AnimationView.swift decodes frames with ImageIO and drives the timing itself, so state changes restart cleanly.
• EventServer.swift is a ~100-line Unix socket listener; shell/terminal-pet.plugin.zsh is the client.

Contributing

New pets, new terminals, and new shells are the best ways to help. See CONTRIBUTING.md; adding a pet is about 60 lines of Swift.

Roadmap

• Sound / notification on long command completion
• tmux awareness (which pane is active)
• Linux (X11/Wayland overlay) and Windows

License

MIT