Skip to content
Back to search

cinetty

SkillWorks with Claude CodeGitHub

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/josssphzhou--cinetty/badge.svg)](/listings/josssphzhou--cinetty)

HTML

<a href="/listings/josssphzhou--cinetty"><img src="/api/listings/josssphzhou--cinetty/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 121 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: cinetty
  3. 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.
  4. ---
  5. # cinetty
  6. 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/`.
  7. ## Install
  8. Run this once. It needs Python 3.12 or newer (or uv), Bash and Make on macOS or Linux.
  9. ```sh
  10. make setup
  11. ```
  12. `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.
  13. 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.
  14. ## 1. Choose a template
  15. ```sh
  16. make templates FORMAT=json
  17. ```
  18. 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.
  19. | Template | Fits a system that |
  20. |---|---|
  21. | `loop-landscape` | improves itself over rounds: propose, try candidates, keep what helped (wide) |
  22. | `loop-portrait` | has a fast live loop on top and a slow learning loop below (tall) |
  23. | `photo-loop` | reads real photos with a vision model while a background loop improves it |
  24. | `pipeline` | plans work and has a router hand each step to one to three workers (agents, people or services), with an advisor that steps in |
  25. | `screen-flow` | is an agent that operates a phone or another screen |
  26. | `circuit-flow` | has about eight parts with signals running along wires (boards, services); the board always shows eight modules and sixteen wires |
  27. If you chose `photo-loop`, install the photo dependencies and two local models before preparing or playing it:
  28. ```sh
  29. make setup-photo
  30. ```
  31. 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.
  32. ## 2. Write project.yaml
  33. 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.
  34. 2. Read the example project named in `example`. It is a complete file that passes the check.
  35. 3. Read the user's repository. Write `project.yaml` where the user wants it:
  36. ```yaml
  37. template: <id>
  38. template_version: 1
  39. name: my-project
  40. fields:
  41. ... # every field from template.yaml
  42. ```
  43. `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.
  44. Rules for the content:
  45. - 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.
  46. - 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 `--`).
  47. - 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.
  48. - 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.
  49. - Widths are terminal cells. A CJK character counts as 2.
  50. - Do not separate words with a spaced dot (` · ` or ` • `). Use a colon, a comma or another field.
  51. - Text is shown literally. Braces are not variables, except where a field lists `placeholders` such as `{n}`.
  52. - One `project.yaml` holds one language. For a second language, copy it and translate the text.
  53. - 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.
  54. - 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.
  55. ## 3. Check until it passes
  56. ```sh
  57. make check INPUT=path/to/project.yaml FORMAT=json
  58. ```
  59. 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`.
  60. 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`.
  61. ## 4. Play it
  62. ```sh
  63. make play INPUT="path/to/project.yaml"
  64. ```
  65. 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`.
  66. 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.
  67. - `photo-loop` needs a terminal that supports the Kitty graphics protocol (Ghostty, Kitty, WezTerm). The other five templates use text cells only.
  68. - `screen-flow` plays the board alone.
  69. To keep a video, record the terminal with the user's own screen recorder.
  70. ## Common problems
  71. | Code | What to do |
  72. |---|---|
  73. | `too_long`, `too_long_on_screen` | Follow the hint: shorten the text at the path by the number of cells it names. When the hint names several fields, the total of the cuts must reach that number. |
  74. | `too_many`, `too_few` | The template takes a fixed or limited number of items at that path. |
  75. | `missing`, `empty`, `unknown_field` | Use exactly the fields in `template.yaml`; every required field needs a value. |
  76. | `unknown_ref` | Use one of the names the hint lists; references must name an item that exists. |
  77. | `out_of_range` | Use a value inside the range in the hint, or add the items it asks for. |
  78. | `count_mismatch` | A count disagrees with the numbers it counts, for example `fallbacks` against `confidences` and the gate. Write the number the hint gives, or change the numbers or the gate. |
  79. | `wrong_type` | Quote text that YAML would read as a number, a date or a mapping, for example `'roles: admin'`. |
  80. | `time_goes_back`, `bad_time` | Event times are seconds from the start and never decrease. |
  81. | `unknown_event` | Use the event types listed under `events` in `template.yaml`. |
  82. | `spaced_dot` | Replace the spaced dot with a colon or a comma, or move the second part into another field. |
  83. | `unsure_width` | Replace the symbol the hint names with another one, for example a symbol from the template's example. Terminals disagree on its width. |
  84. | `no_split` | Write the text as `<before> → <after>`, for example `v1 → v3`. The comparison's divider runs through the arrow. |
  85. | `cannot_draw` | Two fields disagree, for example a count larger than its list. Fix the round named in the path. |
  86. ## Changing a layout
  87. 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.
README.md · README · 239 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <b>English</b> | <a href="README.zh-CN.md">简体中文</a> | <a href="README.ja.md">日本語</a>
  3. </p>
  4. <p align="center">
  5. <p align="center"><img src="docs/logo.png" alt="cinetty" width="476"></p>
  6. <p align="center"><b>Cinematic architecture animations that play directly in your terminal.</b></p>
  7. </p>
  8. <p align="center">
  9. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
  10. <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="Python 3.12+"></a>
  11. <a href="https://github.com/JosssphZhou/cinetty"><img src="https://img.shields.io/badge/terminal-Kitty%20%7C%20ANSI-orange.svg" alt="Terminal Kitty / ANSI"></a>
  12. <a href="https://x.com/openmys"><img src="https://img.shields.io/badge/author-@openmys-black.svg" alt="X @openmys"></a>
  13. </p>
  14. <p align="center">
  15. <a href="docs/hero.mp4"><img src="docs/hero.gif" width="100%" alt="cinetty demo"></a>
  16. </p>
  17. <p align="center">
  18. Pick a template, describe your system in a single YAML file, check constraints, and watch your architecture come alive in terminal cells.
  19. </p>
  20. <p align="center">
  21. <a href="#templates-gallery">Templates Gallery</a> |
  22. <a href="#how-it-works">How It Works</a> |
  23. <a href="#requirements">Requirements</a> |
  24. <a href="#quick-start">Quick Start</a> |
  25. <a href="#use-it-as-a-skill">Use as a Skill</a> |
  26. <a href="#make-your-own">Make Your Own</a> |
  27. <a href="#license">License</a>
  28. </p>
  29. ---
  30. ## Templates Gallery
  31. <p align="center">
  32. <a href="templates/loop-landscape/"><img src="templates/loop-landscape/preview/clip.gif" width="720" alt="loop-landscape"></a><br>
  33. <a href="templates/loop-landscape/"><code>loop-landscape</code></a>
  34. </p>
  35. <p align="center">
  36. <a href="templates/circuit-flow/"><img src="templates/circuit-flow/preview/clip.gif" width="720" alt="circuit-flow"></a><br>
  37. <a href="templates/circuit-flow/"><code>circuit-flow</code></a>
  38. </p>
  39. <p align="center">
  40. <a href="templates/screen-flow/"><img src="templates/screen-flow/preview/clip.gif" width="720" alt="screen-flow"></a><br>
  41. <a href="templates/screen-flow/"><code>screen-flow</code></a>
  42. </p>
  43. <p align="center">
  44. <a href="templates/loop-portrait/"><img src="templates/loop-portrait/preview/clip.gif" width="360" alt="loop-portrait"></a><br>
  45. <a href="templates/loop-portrait/"><code>loop-portrait</code></a>
  46. </p>
  47. <p align="center">
  48. <a href="templates/photo-loop/"><img src="templates/photo-loop/preview/clip.gif" width="360" alt="photo-loop"></a><br>
  49. <a href="templates/photo-loop/"><code>photo-loop</code></a>
  50. </p>
  51. <p align="center">
  52. <a href="templates/pipeline/"><img src="templates/pipeline/preview/clip.gif" width="360" alt="pipeline"></a><br>
  53. <a href="templates/pipeline/"><code>pipeline</code></a>
  54. </p>
  55. Each preview illustrates the template in action. Click any card to inspect its template schema, scene configuration, and example project.
  56. 🎬 **10-Second Demo Clip**: [docs/hero.mp4](docs/hero.mp4)
  57. ---
  58. ## How It Works
  59. cinetty is a template library for terminal animations, much like a curated pack of After Effects templates:
  60. - **Pre-choreographed Motion**: Every template is a finished, polished animation featuring a fixed coordinate grid, cohesive color palette, engineered rhythm, and named content slots.
  61. - **YAML-driven**: You only define your components, values, and timed events in a single YAML file. The layout stays locked and pixel-perfect.
  62. - **Terminal-native & Protocol-aware**: The engine renders crisp animations directly onto terminal text cells. Photo templates integrate image assets via the Kitty graphics protocol.
  63. - **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](AGENTS.md).
  64. ---
  65. ## Requirements
  66. - **Operating System**: macOS or Linux, with Bash and Make.
  67. - **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`).
  68. - **Runtime**: Python 3.12 or newer, or [uv](https://docs.astral.sh/uv/).
  69. - **Disk Space**:
  70. - Text templates: `make setup` installs only the three lightweight packages needed for text rendering (about 73 MB, completed in seconds).
  71. - Photo template: `make setup-photo` adds PyTorch and two vision models (about 2 GB).
  72. - **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.
  73. ---
  74. ## Quick Start
  75. ```sh
  76. # Clone the repository and navigate into it
  77. git clone https://github.com/JosssphZhou/cinetty.git cinetty && cd cinetty
  78. # Fast setup: install text-template dependencies into .venv (about 73 MB)
  79. make setup
  80. # Play an example animation
  81. make play INPUT=examples/circuit-flow/project.en.yaml
  82. ```
  83. For the photo template (`photo-loop`), download the vision models first:
  84. ```sh
  85. # Add PyTorch and vision models (about 2 GB)
  86. make setup-photo
  87. # Prepare the photos and play the photo example
  88. make play INPUT=examples/harness-photo/project.en.yaml
  89. ```
  90. ### Controls & Tips
  91. - **Stop Playback**: Press `Ctrl-C` at any time.
  92. - **Looping**: Pass `LOOP=1` to repeat playback continuously (`make play INPUT=... LOOP=1`).
  93. - **Preview Alias**: `make preview` is an alias for `make play`.
  94. - **Terminal Sizing**: If the player warns about insufficient terminal cells, maximize your terminal window or decrease font size (`Cmd -`).
  95. - **Screen Recording**: Record your terminal window directly using your preferred recording tool to generate video clips or GIFs.
  96. ---
  97. ## Use It as a Skill
  98. 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](AGENTS.md) contains the equivalent workflow for other agents.
  99. | Environment | All Projects (Global) | Single Project Only |
  100. |---|---|---|
  101. | Claude Code | `~/.claude/skills/cinetty` | `.claude/skills/cinetty` in project root |
  102. | Codex | `~/.agents/skills/cinetty` | `.agents/skills/cinetty` in project root |
  103. ```sh
  104. git clone https://github.com/JosssphZhou/cinetty.git ~/.claude/skills/cinetty && make -C ~/.claude/skills/cinetty setup
  105. ```
  106. > Directory structures verified on 2026-10-21 against [Claude Code skills](https://code.claude.com/docs/en/skills) and [Codex skills](https://developers.openai.com/codex/skills).
  107. ---
  108. ## Templates
  109. Run the following command to view the catalog of all available templates:
  110. ```sh
  111. make templates
  112. ```
  113. | Template | Concept | Terminal Grid | Duration |
  114. |---|---|---|---|
  115. | [`loop-landscape`](templates/loop-landscape/) | An agent harness that improves itself over three rounds, scored by a decision core | 120 × 40 cells | ~35 s |
  116. | [`loop-portrait`](templates/loop-portrait/) | A fast live decision loop on top, a slow learning loop below that improves it | 66 × 48 cells | ~37 s |
  117. | [`photo-loop`](templates/photo-loop/) | A vision model reads real photos with live box effects while a background loop improves it | 66 × 48 cells (Kitty images) | ~36 s (28 s with two rounds) |
  118. | [`pipeline`](templates/pipeline/) | A main agent plans, a router dispatches to one to three workers, an advisor steps in at three moments | 90 × 46 cells | 15 s per cycle |
  119. | [`screen-flow`](templates/screen-flow/) | An agent operates a phone: OCR, a decision model, a pixel-only fallback, and two devices | 94 × 37 cells | 26 s |
  120. | [`circuit-flow`](templates/circuit-flow/) | Eight modules light up as signals run along the wires between them | 120 × 40 cells | 44 s |
  121. Each template directory contains:
  122. - `template.yaml`: Field schema, definitions, types, and cell budget limits.
  123. - `scene.yaml`: Layout definitions, coordinate bounds, and color slots.
  124. - `preview/`: A still frame (`still.png`) and demo animation clip (`clip.gif` / `clip.mp4`).
  125. Every template includes at least one complete example under `examples/`. See `examples/web-service/` for an adaptation of the circuit template to web microservices.
  126. ---
  127. ## Make Your Own
  128. ### 1. Pick a template
  129. Run `make templates` and read `template.yaml` in your chosen template directory.
  130. ### 2. Create your project file
  131. Copy an example project and replace the content with your own system definition:
  132. ```yaml
  133. template: circuit-flow
  134. template_version: 1
  135. name: my-service
  136. credit: false # Optional: set to false to omit the "made with cinetty" footer
  137. fields:
  138. title: MY SERVICE
  139. # ...
  140. events:
  141. - {t: 3.0, type: light, box: A, until: 7.0}
  142. # ...
  143. ```
  144. ### 3. Check layout constraints
  145. Validate that your text fits the allocated terminal cell budgets:
  146. ```sh
  147. make check INPUT=my-service.yaml
  148. ```
  149. Every issue identifies the exact field path and cell overflow:
  150. ```text
  151. too_long: fields.modules.B.name (38 > 34): shorten to at most 34 cells (a CJK character counts as 2)
  152. ```
  153. Widths are measured in terminal cells (a Chinese / CJK character counts as two cells). The checker never auto-truncates text for you.
  154. ### 4. Play it
  155. Run the player in your terminal:
  156. ```sh
  157. make play INPUT=my-service.yaml
  158. ```
  159. Note that `screen-flow` renders the terminal board alone.
  160. ### Additional Guides
  161. - **Localization**: One project file holds one language. To create a second language version, copy the YAML file and translate its string values.
  162. - **Custom Layouts**: To customize visual layouts rather than content, see [docs/scene-reference.md](docs/scene-reference.md).
  163. - **Architecture & Engine**: See [docs/design.md](docs/design.md) for how the engine components fit together.
  164. ---
  165. ## Author
  166. Created by Joseph Zhou ([@openmys](https://x.com/openmys)).
  167. Feedback, issue reports, and template contributions are welcome!
  168. ---
  169. ## License
  170. - **Code and Templates**: MIT License (see [LICENSE](LICENSE)).
  171. - **Sample Photos**: CC0 (Public Domain).
  172. - **Pre-trained Models**: Apache-2.0 License.
  173. - **Third-Party Assets**: Complete list of third-party assets and sources in [LICENSES.md](LICENSES.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.