terminal-tiger

Photographic, animated portraits for your terminal and your AI coding agents. A tiger (or your dog, your logo, your face) that reveals itself when you open a shell or start Claude Code, Codex or Gemini CLI.

Live playground · Quick start · AI agents · Make it yours · Share it · How it works

Built at Google for Startups · Los Angeles Tech Week 2026

Quick start

Try it without installing anything (needs uv):

uvx terminal-tiger

Install it and set it up:

uv tool install terminal-tiger
tiger --install-shell --wrap

Open a new terminal to meet your tiger. It greets you once a day when a shell opens. --wrap also plays it every time you start claude, codex or gemini. Both live in one marked block in your ~/.zshrc, ~/.bashrc or fish config (whichever shell you use). Delete the block to undo.

No uv? Use pipx install terminal-tiger. The first run downloads the tiger photo into ~/.cache/terminal-tiger/. After that it works offline.

In Claude Code, Codex & Gemini CLI

With --wrap, claude plays the reveal at double speed and then starts Claude Code as usual. Ctrl-C skips straight to the agent.

• Headless runs stay clean. claude -p, codex exec, gemini -p and --version get no portrait. Neither do commands an agent runs itself, because they have no terminal attached.
• IDE terminals too. VS Code, Cursor and Antigravity load your shell, so their built-in terminals get the greeting and the launchers.
• Any command. tiger --install-shell --wrap claude aider wraps the commands you name instead.

Tune it with a [greet] table in your config:

[greet]
preset = "cookie"     # which portrait to show (default: your default preset)
speed = 3             # animation tempo (default 2)
once_a_day = true     # only the first launch of each agent per day

A pet for Codex

The Codex CLI can keep an animated pet beside its prompt. Make yours:

tiger --codex-pet             # or: tiger cookie --codex-pet

This writes ~/.codex/pets/tiger/. Pick it in Codex's pet menu, or set pet = "custom:tiger" under [tui] in ~/.codex/config.toml. Its eyes burn while Codex waits for you, the reveal ripple loops while it thinks, and it turns gray when it's blocked. Codex draws pets in terminals with Kitty graphics or Sixel (Ghostty, Kitty, WezTerm, iTerm2 3.6+, Windows Terminal), outside tmux.

Make it yours

Any photo works. Front-facing, evenly lit, on a plain or dark background works best.

tiger ~/Pictures/cookie.jpg --title cookie
tiger https://example.com/logo.png --reveal iris --accent "#3fa9ff"

Finding the eyes: open the image in any editor and read the pixel coordinates of each pupil. Subtract the crop's left/top edge, then divide by the crop's width/height. Or just guess, run it, and nudge. It takes about a minute.

Presets & config

Save your look in ~/.config/terminal-tiger/config.toml (see examples/config.toml):

preset = "cookie"            # what `tiger` shows with no arguments

[style]                      # applies to every preset
subtitle = "welcome back, {user}"

[presets.cookie]
image = "~/Pictures/cookie.jpg"
crop = [0.10, 0.00, 0.90, 0.85]
eyes = [[0.40, 0.42], [0.60, 0.42]]
title = "cookie"
accent = "#ffd166"

Settings are applied in this order, each overriding the last: built-in defaults → built-in preset → [style] → [presets.NAME] → command-line flags. Run tiger --list to see your presets.

Share it

• Your look, as a link. Pick a reveal, accent and title in the playground, then press Copy link. Whoever opens it sees your version and gets the matching command.
• Your preset. A preset is a few lines of TOML, and image can be a URL, so one pasted into a gist or your dotfiles works on any machine.
• A GIF. tools/make_demo.py records the real CLI to a GIF, headless.
• The showcase. Made something great? Open a PR that adds it below.

Showcase

Top row: mid-reveal. Bottom row: finished. Left to right: --reveal iris --accent "#3fa9ff", --reveal scan --accent "#7cff6b", --mode 256 --reveal dissolve --accent "#ff4fd8".

How it works

The project started as a plain ASCII tiger that looked like static. These are the changes that turned it into a portrait, roughly in order of impact:

1. Half-block pixels. Each character cell prints ▀ with a 24-bit foreground color (the top pixel) and a 24-bit background color (the bottom pixel). That gives two square-ish pixels per cell, full color, and no aspect-ratio squash. Brightness-ramp ASCII throws all that color away.
2. Pick the right photo. A dark background, a front-facing pose and both ears in frame mattered more than any code change.
3. Contrast without changing the colors. Plain autocontrast stretches the R, G and B channels separately, which turned brown fur red. preserve_tone=True stretches brightness only.
4. A vignette fades the edges into your terminal background, so the portrait floats instead of sitting in a rectangle. The background color comes from the terminal itself (an OSC 11 query), so it matches without setup.
5. The tmux trap. Google Cloud Shell runs inside tmux 2.1, which silently converts 24-bit color to 256 colors (truecolor passthrough arrived in tmux 2.2). --mode direct detects this and writes straight to the client's tty with tmux display -p '#{client_tty}', skipping tmux entirely.
6. A 256-color fallback that still looks good. For terminals without truecolor, the image is Floyd–Steinberg dithered into the xterm-256 palette with perceptual weights, so browns don't collapse into maroon.
7. The reveal. Every cell gets a start time from its distance to the eyes, plus a little noise, so the edge looks organic instead of a perfect circle. It fades up from black through a flash of the accent color. Only cells that change are redrawn, at roughly 30 fps. Cells are positioned with save/restore cursor and relative moves, so it draws inline under your prompt without clearing the screen.

Terminal support

Output that is piped or redirected gets static lines with no cursor movement, so tiger > tiger.ans && cat tiger.ans works.

Record your own demo

tools/make_demo.py runs the real CLI inside a virtual terminal (a pty plus pyte) and turns the byte stream into a GIF. No screen recorder is needed, and it works headless:

uv run tools/make_demo.py docs/mine.gif --bg "#1d1f21" -- ~/me.jpg --title me --bg "#1d1f21"

Development

uv run pytest            # tests: config, dithering, reveal timing, rendering, shell hooks, Codex pet

The CLI is a single, dependency-light file (terminal_tiger.py) with inline PEP 723 metadata, so it even runs straight from GitHub with nothing installed: uv run https://raw.githubusercontent.com/joshogden360/terminal-tiger/main/terminal_tiger.py. Its source is ASCII-only on purpose, so it can be pasted or typed into any terminal, even through a browser. See CONTRIBUTING.md.

Credits

• Built at Google for Startups · Los Angeles Tech Week 2026 by Josh Ogden.
• Default photo: “Bengal Tiger Portrait” by Shootsalot, licensed CC BY-SA 4.0, via Wikimedia Commons. The photo is not included in this repository. It is downloaded on first run.
• docs/demo.gif, docs/demo.png, docs/styles.png, docs/og.png, the pet preview and the cell data embedded in docs/index.html are renderings of that photo, and are shared under CC BY-SA 4.0. See CREDITS.md.
• Code: MIT.