⚜ zoetty

What is zoetty?

zoetty turns terminal sessions into small, looping, animated clips made of plain SVG or HTML and CSS. No video, no GIF, no JavaScript.

That's zoetty, recorded by zoetty. Every clip in this README is built from a spec in docs/clips/.

Why use zoetty?

Terminal GIFs go stale, weigh megabytes, look blurry, and have to be re-recorded by hand every time the output changes.

• Real output - zoetty record runs your commands in a real terminal and keeps their colours.
• Small and sharp - A clip is a few KB of text, crisp at any size.
• Works in READMEs - The SVG is just an image: it plays on GitHub, PyPI and anywhere else that shows one.
• Or in your docs - The HTML fragment drops into any page, with selectable text.
• Kept in your repo - The spec is a short TOML file. When your tool changes, re-record and rebuild.
• Checked in CI - zoetty check fails if a clip is out of date.

Install

uv tool install zoetty

Or with pip:

pip install zoetty

zoetty needs Python 3.12 or later, and runs on macOS and Linux.

Quick start

zoetty init docs/clips/hello.toml    # write a starter spec
zoetty build docs/clips/hello.toml   # render it to docs/clips/hello.svg

Then put it in your README like any image:

![What the clip shows](docs/clips/hello.svg)

A basic clip

Two commands, with their output written by hand:

title = "~/my-project"
label = "Typing two commands in a terminal: echo prints a greeting, ls lists three files"
cols = 60

[[run]]
cmd = "echo 'Hello from zoetty!'"
lines = ["Hello from zoetty!"]

[[run]]
cmd = "ls"
lines = ["[blue]docs[/]  README.md  [green]tool.py[/]"]

Recording real output

Give a run an output file and zoetty record runs the command for real and saves what it printed. input is typed into interactive programs, a line at a time, once each prompt is waiting:

title = "python"
label = "A Python REPL importing zoetty's markup parser and parsing some styled text"
cols = 64

[record]
env = { PYTHON_BASIC_REPL = "1" }

[[run]]
cmd = "python -q"
output = "captures/repl.ansi"
input = """
from zoetty.markup import parse, plain
plain(parse("[bold]zoe[/]tty"))
[s.styles for s in parse("[bold green]ok[/] done")]
"""

zoetty record docs/clips/repl.toml
zoetty build docs/clips/repl.toml

Long output scrolls once it passes rows, and [theme] recolours the whole window:

See more examples, including the HTML output and hand-timed clips.

Use it with your coding agent

zoetty is easy for coding agents to drive: specs are small text files, and every command says what it did. Paste this into Claude Code, Codex, Cursor or similar:

Use zoetty to add an animated terminal demo of this project to the README.
Read https://phalt.github.io/zoetty/agents/ first and follow it: install zoetty,
write a clip spec in docs/clips/ that shows the most useful commands, record the
real output with `zoetty record`, build it with `zoetty build`, look at the result,
embed the SVG in README.md, and add `zoetty check docs/clips/*.toml` to CI.

Documentation

👉 Read the full documentation for the clip format, every command, embedding clips and more examples.

Want to help? See CONTRIBUTING.md.