Turn the arrows and lines in a static image into a moving-dot GIF.
Built for architecture diagrams, pipelines, workflows and technical explainers.
Quick start · Install the skill · Map your image · Configuration
Your image stays still. The dots tell the story.
| 1. Start with a static image | 2. Add flow-dot motion |
|---|---|
 |
|
| Keep your layout, labels and arrows. | Export a GIF you can embed or share. |
How it works: an AI assistant inspects the image and maps its connector paths. A local renderer moves dots along those measured paths at constant speed. You can also write the route file yourself and use the CLI directly.
This is AI-assisted mapping with deterministic rendering. The script does not automatically detect every line in an image.
| Use case | Show the flow |
|---|---|
| System architecture | Requests between clients, gateways and services |
| CI/CD pipelines | Progress through build, test and deployment steps |
| Event-driven systems | Messages moving between producers and consumers |
| Workflows and teaching | Direction through a process without moving its labels |
- Follow the actual path: straight, diagonal, bent, or curved with sampled points.
- Keep the artwork still: only the dot overlays animate.
- Control the motion: colour, diameter, speed, starting phase and direction per route.
- Work at your image size: no fixed aspect ratio or branded template.
- Render locally: Python, Pillow and FFmpeg. No rendering API or API key.
- Inspect before exporting: a route preview shows your mapped centreline and direction.
You need Python 3.10+ and FFmpeg on PATH. Install FFmpeg using your operating system's package manager, for example brew install ffmpeg on macOS or sudo apt install ffmpeg on Ubuntu. See FFmpeg downloads for other platforms.
git clone https://github.com/truptik-devops-pro/tk-flowdot-studio.git
cd tk-flowdot-studio
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r skills/tk-flowdot-studio/requirements.txt
ffmpeg -version
mkdir -p outputOn Windows PowerShell, use py -m venv .venv and .venv\Scripts\Activate.ps1 instead of the two environment commands above. Use single-line versions of commands below in PowerShell, where \ is not a continuation character.
Preview the demo's measured routes:
python skills/tk-flowdot-studio/scripts/flowdot.py preview \
--image examples/demo.png \
--config examples/demo.json \
--output output/routes-preview.pngConvert the demo image to a GIF:
python skills/tk-flowdot-studio/scripts/flowdot.py render \
--image examples/demo.png \
--config examples/demo.json \
--output output/demo.gifOpen output/demo.gif. Existing output files are protected; choose a new filename or explicitly add --force to replace one.
The self-contained skill lives in skills/tk-flowdot-studio. Keep its instructions, script, requirements and reference together.
With a GitHub CLI version that supports the preview gh skill commands, install for Codex at user scope:
gh skill install truptik-devops-pro/tk-flowdot-studio tk-flowdot-studio --agent codex --scope userSee the GitHub CLI installation reference for other agent destinations and version pinning. Runtime requirements below still apply.
You can also discover and install the skill through the Skills CLI:
npx skills add truptik-devops-pro/tk-flowdot-studioChoose your agent when prompted. This installs the skill files; install Python, Pillow and FFmpeg separately as described in Quick start.
Ask Codex's skill installer:
Use $skill-installer to install the skill from
https://github.com/truptik-devops-pro/tk-flowdot-studio/tree/main/skills/tk-flowdot-studio
Restart or refresh your agent's skill discovery after installing. The Python environment still needs Pillow and FFmpeg as described above.
For a manual install from this repository, copy the complete skill folder into ~/.agents/skills/tk-flowdot-studio, checking that it does not already exist. This is Codex's documented user-level skills location. See OpenAI's local skill documentation.
For agents that support the Agent Skills format, copy the whole skills/tk-flowdot-studio directory into that agent's documented skills location. Shell execution, image inspection, Python and FFmpeg are required. Loading SKILL.md alone does not install runtime dependencies. Agent-specific compatibility beyond Codex has not been tested.
Attach your diagram, or provide its local file path:
Use $tk-flowdot-studio to animate the arrows in this image.
Use teal flow dots moving toward the arrowheads.
Keep all text, icons and the background unchanged.
Inspect the route preview, then export the GIF and route JSON.
For preview only, add: Show me the route preview and wait before rendering.
- Export your diagram as a static PNG or JPEG.
- Ask the skill to inspect it and map the line centrelines, or write your own route JSON.
- Inspect the route preview at the original resolution. Correct any line, bend or direction that is wrong.
- Render the GIF and inspect it at the size where you will share it.
Start with the practical guide, then use the configuration reference for exact field names. The demo includes its source SVG, PNG and route JSON.
- Curves use closely spaced polyline points. Native SVG paths and automatic line tracing are not included.
- Dots wrap at each route's endpoint. Independent route periods may cause a visible reset when the whole GIF restarts. Seamless loops require matching periods.
- GIF reduces the image to a shared colour palette. Transparent input is flattened onto white.
- Existing stationary dots remain in your image. The renderer does not erase or redesign the source.
- Branches animate independently. This is a visual explainer, not a traffic simulator.
python -m unittest discover -s tests -vTests exercise geometry, input validation, file protection and actual GIF output. FFmpeg is required for the integration checks. See CONTRIBUTING.md for focused contributions.
Created by Trupti Kolekar to make technical diagrams easier to explain. TK FlowDot Studio generalizes the constant-speed, measured-centreline motion technique from her original NGINX animation workflow. The demo artwork is original and the reusable skill contains no fixed NGINX layout or branding.
Released under the MIT License.