name: cinetty description: Make an animated architecture diagram that plays in the terminal, from one of six finished templates (agent harness loops, a vision model on photos, an agent workflow with a router and workers, a phone-operating agent, a circuit or service board with signals on wires). Use when the user asks for an architecture animation, an animated flow chart, a terminal video or a demo clip of how their system works, in English or Chinese (for example 架构动画, 终端流程图, 给项目做一支动画). The skill reads the user's repository, fills one project.yaml, checks it until it passes and plays it in the current terminal. Do not use it for static diagrams such as Mermaid, PlantUML or draw.io, for README or documentation writing, or for screen recordings of a running app.

cinetty

Run every command in this file from the directory that holds this file: the cinetty repository root. cinetty turns one project.yaml into an architecture animation that plays in the current terminal. Each template is a finished animation with a fixed layout, palette and rhythm, plus named fields. You fill the fields with the user's system; you never edit the layout. Everything you need is in this file and the files it names: make templates, each template.yaml and its example. You do not need to read the code in cinetty/ or scripts/.

Install

Run this once. It needs Python 3.12 or newer (or uv), Bash and Make on macOS or Linux.

make setup

make setup creates .venv and installs the light dependencies for the five text templates and checks for all examples. It does not install photo dependencies or download models. Everything stays inside this directory. If it stops, its last line names what is missing.

Both installation commands need network access. If the command fails because the network is blocked, ask the user to run the same command in their own terminal, then continue. Do not install the packages some other way, and do not use another project's Python environment.

1. Choose a template

make templates FORMAT=json

Each entry has id, kind (video), terminal (the size it needs), duration, purpose, a preview path and the path of a filled example. Pick the template whose purpose matches the shape of the user's system, not its subject. Decide by shape before you look at which facts you have, and keep that template; missing facts are handled in step 2, never by switching templates.

If you chose photo-loop, install the photo dependencies and two local models before preparing or playing it:

make setup-photo

The shipped examples include source photos and detection results, but not the prepared outlines and animation images. Their first play also needs make setup-photo. Content checks with make check work with the light installation.

2. Write project.yaml

1. Read templates/<id>/template.yaml. Its fields section lists every field with its type, whether it is required, max_cells, item counts, number ranges and enum values. Its notes say what each part of the picture shows.

2. Read the example project named in example. It is a complete file that passes the check.

3. Read the user's repository. Write project.yaml where the user wants it:

   template: <id>
   template_version: 1
   name: my-project
   fields:
     ...            # every field from template.yaml
   

   pipeline, screen-flow and circuit-flow also take events:, a list of timed steps, or the path of a .jsonl file with one event per line. Every event has t (seconds from the start, never decreasing) and type. The other keys depend on the type and are listed under events in template.yaml. The example shows a complete timeline.

Rules for the content:

• Fill fields from facts in the user's repository or from what the user told you. Do not present invented numbers or results as real.
• Every number on the screen comes from a field or an event of the project. The engine makes up none: a live loop shows the confidences you list, a counter changes only where an event gives a new value, and a number you leave out of an optional field is not shown (a status value shows --).
• When the user only names a system in a sentence and there is no repository to read, do not stop to ask. Design an illustrative architecture from that sentence: the parts, names and steps it implies. Keep the example's numbers (scores, confidences, counts, timings) as placeholders. In your reply, say that the picture is illustrative and list the fields that still hold the example's numbers.
• The photo template (photo-loop) uses the user's own photos. If the user has none, use the two sample photos in assets/photos/ with the blur rectangles from the example, and say so in your reply. Preparing photos runs local models only.
• Widths are terminal cells. A CJK character counts as 2.
• Do not separate words with a spaced dot (· or •). Use a colon, a comma or another field.
• Text is shown literally. Braces are not variables, except where a field lists placeholders such as {n}.
• One project.yaml holds one language. For a second language, copy it and translate the text.
• File fields (photos) are paths relative to project.yaml. Use only photos the user may publish; blur faces and number plates with the blur field.
• A small made with cinetty appears at the bottom. Keep it unless the user asks to remove it; then add credit: false at the top level.

3. Check until it passes

make check INPUT=path/to/project.yaml FORMAT=json

The command exits non-zero when something is wrong and lists every problem with a code, the field path and a hint. A length problem also has actual, limit and over, and its hint names the exact change, for example fix: shorten by 6 cells, to at most 34 cells. The check also plays the whole animation and reports text that does not fit on screen, with the time and round.

Do what each hint says, then run the check again. Repeat until it prints no problems. Never work around a limit: do not add spaces, split a word over two fields or edit template.yaml.

4. Play it

make play INPUT="path/to/project.yaml"

The animation plays in the current terminal, which must be at least as large as the template's terminal size from step 1 (for example 120 x 40 cells). Ctrl-C stops it; LOOP=1 repeats it. If the player asks for more cells, enlarge the terminal or reduce its font size. make play needs an interactive terminal. If your shell runs without one, it stops with a message; then ask the user to run the same command in their terminal. To see one moment as text, run make once INPUT="path/to/project.yaml" AT=12.

A video ends by itself after its duration and 6 more seconds on the last frame. The first play of photo-loop prepares the photos with local models, which can take several minutes; later plays reuse them.

• photo-loop needs a terminal that supports the Kitty graphics protocol (Ghostty, Kitty, WezTerm). The other five templates use text cells only.
• screen-flow plays the board alone.

To keep a video, record the terminal with the user's own screen recorder.

Common problems

Changing a layout

Layouts live in templates/<id>/scene.yaml and are drawn by the engine in cinetty/. Edit them only when the user asks for a different layout; docs/scene-reference.md describes the format. Content never needs a layout change.

Templates Gallery

Each preview illustrates the template in action. Click any card to inspect its template schema, scene configuration, and example project.

🎬 10-Second Demo Clip: docs/hero.mp4

How It Works

cinetty is a template library for terminal animations, much like a curated pack of After Effects templates:

• Pre-choreographed Motion: Every template is a finished, polished animation featuring a fixed coordinate grid, cohesive color palette, engineered rhythm, and named content slots.
• YAML-driven: You only define your components, values, and timed events in a single YAML file. The layout stays locked and pixel-perfect.
• Terminal-native & Protocol-aware: The engine renders crisp animations directly onto terminal text cells. Photo templates integrate image assets via the Kitty graphics protocol.
• Agent-first Workflow: The easiest way to create an animation is letting your AI coding agent do the work. The agent inspects your codebase, selects the right template, writes the project YAML, runs make check until all layout constraints pass, and plays the result. Guidelines for coding agents are documented in AGENTS.md.

Requirements

• Operating System: macOS or Linux, with Bash and Make.
• Terminal Support: Any terminal for standard text templates. A terminal supporting the Kitty graphics protocol (such as Ghostty, Kitty, or WezTerm) is required for the photo template (photo-loop).
• Runtime: Python 3.12 or newer, or uv.
• Disk Space:
  • Text templates: make setup installs only the three lightweight packages needed for text rendering (about 73 MB, completed in seconds).
  • Photo template: make setup-photo adds PyTorch and two vision models (about 2 GB).
• Optional Font (for Chinese text): Sarasa Term SC (brew install --cask font-sarasa-gothic) for optimal CJK terminal cell alignment. Without it, macOS falls back to default system CJK fonts.

Quick Start

# Clone the repository and navigate into it
git clone https://github.com/JosssphZhou/cinetty.git cinetty && cd cinetty

# Fast setup: install text-template dependencies into .venv (about 73 MB)
make setup

# Play an example animation
make play INPUT=examples/circuit-flow/project.en.yaml

For the photo template (photo-loop), download the vision models first:

# Add PyTorch and vision models (about 2 GB)
make setup-photo

# Prepare the photos and play the photo example
make play INPUT=examples/harness-photo/project.en.yaml

Controls & Tips

• Stop Playback: Press Ctrl-C at any time.
• Looping: Pass LOOP=1 to repeat playback continuously (make play INPUT=... LOOP=1).
• Preview Alias: make preview is an alias for make play.
• Terminal Sizing: If the player warns about insufficient terminal cells, maximize your terminal window or decrease font size (Cmd -).
• Screen Recording: Record your terminal window directly using your preferred recording tool to generate video clips or GIFs.

Use It as a Skill

The repository root includes SKILL.md, enabling the entire clone to operate as a native skill for Claude Code and OpenAI Codex. Install it into your tool's skills directory and run make setup; the agent will automatically invoke cinetty whenever you ask for an architecture animation. AGENTS.md contains the equivalent workflow for other agents.

git clone https://github.com/JosssphZhou/cinetty.git ~/.claude/skills/cinetty && make -C ~/.claude/skills/cinetty setup

Directory structures verified on 2026-10-21 against Claude Code skills and Codex skills.

Templates

Run the following command to view the catalog of all available templates:

make templates

Each template directory contains:

• template.yaml: Field schema, definitions, types, and cell budget limits.
• scene.yaml: Layout definitions, coordinate bounds, and color slots.
• preview/: A still frame (still.png) and demo animation clip (clip.gif / clip.mp4).

Every template includes at least one complete example under examples/. See examples/web-service/ for an adaptation of the circuit template to web microservices.

Make Your Own

1. Pick a template

Run make templates and read template.yaml in your chosen template directory.

2. Create your project file

Copy an example project and replace the content with your own system definition:

template: circuit-flow
template_version: 1
name: my-service
credit: false   # Optional: set to false to omit the "made with cinetty" footer
fields:
  title: MY SERVICE
  # ...
events:
  - {t: 3.0, type: light, box: A, until: 7.0}
  # ...

3. Check layout constraints

Validate that your text fits the allocated terminal cell budgets:

make check INPUT=my-service.yaml

Every issue identifies the exact field path and cell overflow:

too_long: fields.modules.B.name (38 > 34): shorten to at most 34 cells (a CJK character counts as 2)

Widths are measured in terminal cells (a Chinese / CJK character counts as two cells). The checker never auto-truncates text for you.

4. Play it

Run the player in your terminal:

make play INPUT=my-service.yaml

Note that screen-flow renders the terminal board alone.

Additional Guides

• Localization: One project file holds one language. To create a second language version, copy the YAML file and translate its string values.
• Custom Layouts: To customize visual layouts rather than content, see docs/scene-reference.md.
• Architecture & Engine: See docs/design.md for how the engine components fit together.

Author

Created by Joseph Zhou ([@openmys](https://x.com/openm