Skip to content
Back to search

pixel-cat

Turn an image, GIF, video or sprite sheet into pixel art. Agents drive it with shell commands and JSON. Nothing leaves your machine.

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/pyros-projects/pixel-cat with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/pyros-projects/pixel-cat'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pyros-projects--pixel-cat/badge.svg)](/listings/pyros-projects--pixel-cat)

HTML

<a href="/listings/pyros-projects--pixel-cat"><img src="/api/listings/pyros-projects--pixel-cat/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.

npx skills add pyros-projects/pixel-cat -g -s pixel-cat

[skills](https://skills.sh) installs the [`pixel-cat` skill](skills/pixel-cat/SKILL.md) for Claude Code, Codex, Cursor and the other agents it supports. It needs Node.js 22.20 or newer. Leave out `-g` to install the skill for the current project only. Then ask your agent from any folder:

- “Turn ~/Pictures/cat.jpg into a 64-color pixel sprite.” - “Make this screen recording a pixel-art GIF with 16 colors.” - “Make a looping pixel GIF of this landscape with drifting clouds and moving water.” - “Open this sprite in the studio and help me animate a blink.” - “Make a 15-second pixel-art film about a lighthouse keeper winding a clockwork sun.”

On first use the skill clones this repository into `~/.local/share/pixel-cat/app` (on Windows, `%LOCALAPPDATA%\pixel-cat\app`), creates its Python environment and remembers the folder. Your images and films stay in your own folders. The install needs git and uv. FFmpeg is needed for video input, MP4, WebM and films. Say “update pixel-cat” to pull a new version.

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.

README.md · README · 220 lines
  1. <div align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset=".github/logo-dark.svg">
  4. <source media="(prefers-color-scheme: light)" srcset=".github/logo-light.svg">
  5. <img alt="pixel-cat" src=".github/logo-light.svg" width="96" height="96">
  6. </picture>
  7. <h1>pixel-cat</h1>
  8. <p>Turn an image, GIF, video or sprite sheet into pixel art.<br>Agents drive it with shell commands and JSON. Nothing leaves your machine.</p>
  9. </div>
  10. <div align="center">
  11. [![License: MIT][license-shield]][license-url]
  12. [![Python 3.11+][python-shield]][python-url]
  13. [![Version 0.6.5][version-shield]][version-url]
  14. [![Exports PNG, GIF, MP4, WebM][exports-shield]][exports-url]
  15. [![npx skills add pyros-projects/pixel-cat][skill-shield]][skill-url]
  16. [![Runs offline][offline-shield]][offline-url]
  17. </div>
  18. <div align="center">
  19. <a href="#install-as-an-agent-skill">Install as a skill</a> &middot;
  20. <a href="#start">Quick Start</a> &middot;
  21. <a href="#studio">Studio</a> &middot;
  22. <a href="#use-from-an-agent">Use from an agent</a> &middot;
  23. <a href="#make-a-film">Make a film</a> &middot;
  24. <a href="docs/recipes.md">Recipes</a> &middot;
  25. <a href="https://github.com/pyros-projects/pixel-cat/issues/new">Report Bug</a>
  26. </div>
  27. <br>
  28. ---
  29. ## Three 15-second films
  30. <div align="center">
  31. | Tide Bell | Platform Zero | Emberwing |
  32. | :---: | :---: | :---: |
  33. | [![A diver rings a bell beneath the sea](media/tide-bell.gif)](media/tide-bell.mp4) | [![A signalman calls a train through the rain](media/platform-zero.gif)](media/platform-zero.mp4) | [![A moth wakes in a moonlit glasshouse](media/emberwing.gif)](media/emberwing.mp4) |
  34. | [Watch with sound](media/tide-bell.mp4) · [Scene file](examples/films/tide-bell/story.json) | [Watch with sound](media/platform-zero.mp4) · [Scene file](examples/films/platform-zero/story.json) | [Watch with sound](media/emberwing.mp4) · [Scene file](examples/films/emberwing/story.json) |
  35. </div>
  36. Play the MP4s to hear the diver's bell, the lever hitting its stop and the chrysalis cracking. An image model supplied the paintings. The film scripts convert them with pixel-cat, move the props and sprites on a 240 × 360 grid, and synthesize the stereo sound. The camera moves between cells, so zooms and pans stay sharp without shimmering. FFmpeg encodes the 720 × 1080 MP4s. [Artwork prompts](examples/films/ART.md)
  37. ## A 30-second game intro
  38. <div align="center">
  39. [![Roomwright's intro: a room with four sealed doors, a key, a new room, the Warden, a growing floor plan, the logo](media/roomwright-intro.gif)](media/roomwright-intro.mp4)
  40. [Watch with sound](media/roomwright-intro.mp4) · [Scene file](examples/films/roomwright/story.json) · [Play Roomwright](https://play-roomwright.netlify.app) · [Roomwright's source](https://github.com/pyros-projects/roomwright)
  41. </div>
  42. [Roomwright](https://github.com/pyros-projects/roomwright) is a browser game, and this film plays before its title screen. The same film scripts made it, with eight landscape shots on a 400 × 225 grid. An image model painted each shot from a model sheet of the game's own sprites, which kept the hero on model. pixel-cat converted the paintings to 64-color plates, and the key and the glint from the model sheet to sprites. The scene file adds camera moves, a door that jumps with each knock and rooms that pop onto the map one by one. The soundtrack plays the game's title theme, and the cuts fall on its beats. The game drew the logo and the captions in its own font. The captions go on after rendering, so a camera move never touches them. [How it was built](https://github.com/pyros-projects/roomwright/tree/main/intro)
  43. ## Install as an agent skill
  44. ```sh
  45. npx skills add pyros-projects/pixel-cat -g -s pixel-cat
  46. ```
  47. [skills](https://skills.sh) installs the [`pixel-cat` skill](skills/pixel-cat/SKILL.md) for Claude Code, Codex, Cursor and the other agents it supports. It needs Node.js 22.20 or newer. Leave out `-g` to install the skill for the current project only. Then ask your agent from any folder:
  48. - “Turn ~/Pictures/cat.jpg into a 64-color pixel sprite.”
  49. - “Make this screen recording a pixel-art GIF with 16 colors.”
  50. - “Make a looping pixel GIF of this landscape with drifting clouds and moving water.”
  51. - “Open this sprite in the studio and help me animate a blink.”
  52. - “Make a 15-second pixel-art film about a lighthouse keeper winding a clockwork sun.”
  53. On first use the skill clones this repository into `~/.local/share/pixel-cat/app` (on Windows, `%LOCALAPPDATA%\pixel-cat\app`), creates its Python environment and remembers the folder. Your images and films stay in your own folders. The install needs git and uv. FFmpeg is needed for video input, MP4, WebM and films. Say “update pixel-cat” to pull a new version.
  54. ## Start
  55. To work in a clone yourself, use Python 3.11 or newer and uv.
  56. ```sh
  57. git clone https://github.com/pyros-projects/pixel-cat && cd pixel-cat
  58. uv sync --locked
  59. uv run pixel-cat convert examples/images/lake.png -o output/lake.png
  60. uv run pixel-cat convert examples/images/bob.gif -o output/bob.gif --scale 3
  61. ```
  62. ## Studio
  63. <div align="center">
  64. ![The studio: a canvas, tools, a timeline with one row per layer, and a chat in which an agent has just drawn a face on the moon](media/studio.png)
  65. </div>
  66. ```sh
  67. uv run pixel-cat studio sprite.pixelcat --open
  68. ```
  69. The studio is a page on your own machine for drawing and animating. The timeline shows every layer in every frame, so one click picks both. Drop a picture on the canvas and it comes in converted. With `--agent`, the chat is wired to the agent that started it: it sees the frame, the layer and the selection you have open, draws into the same project while you watch, and one Undo takes its changes back. Projects are plain `.pixelcat` files that `convert` reads and writes too. [Studio guide](docs/studio.md)
  70. <img src="media/joints.gif" alt="A desk lamp bows and rises: two arms and a shade, each turning at its joint, and the light follows the shade" width="240" align="right">
  71. Layers can have joints. A part turns around its pivot and hangs on another part, so a hand follows its forearm. You draw each part once, pose two or three frames, and the frames between follow. A flat drawing works too: select a piece, press "part", and it sits on a layer of its own with a joint. This lamp is four drawings and two poses; the light hangs on the shade:
  72. ```sh
  73. uv run pixel-cat studio examples/projects/lamp.pixelcat --open
  74. ```
  75. <br clear="right">
  76. ## Use from an agent
  77. ```sh
  78. uv run pixel-cat catalog
  79. uv run pixel-cat convert examples/images/potion.png --mode grid --grid 64 --sampling ink --colors 12 --scale 1 -o output/sprite.png
  80. uv run pixel-cat convert examples/images/lake.png --mode faithful --width 480 --pixel 4 --palette dusk16 -o output/dusk.png
  81. uv run pixel-cat convert examples/images/spin-sheet.png --sheet 4x2 --delay 80 --mode grid --grid 48 -o output/spin.gif
  82. uv run pixel-cat convert clipboard -o output/pasted.png # the picture on the clipboard
  83. uv run pixel-cat run examples/recipes/bob.json
  84. ```
  85. A successful command prints one JSON object with the grid size, the number of colors, the frame timings and the files it wrote. In recommended mode it also reports the settings it chose, so an agent can repeat or adjust them. Errors go to stderr as JSON with a nonzero exit. A recipe is the same job as a JSON file; it can write several outputs at once and also works over stdin with `pixel-cat run -`. [Recipe reference](docs/recipes.md)
  86. ## Modes
  87. <div align="center">
  88. ![A painted lake at sunset and its pixel art on a 256-cell grid with 32 colors](media/convert-lake.png)
  89. | | | |
  90. | :---: | :---: | :---: |
  91. | ![A potion icon and its 128-cell sprite](media/convert-potion.png) | ![A cartoon rooftop and its 128-cell version with 8 colors](media/convert-rooftop.png) | ![A looping GIF converted frame by frame with one shared palette](media/bob.gif) |
  92. | `pixel-cat convert potion.png -o sprite.png` | `pixel-cat convert rooftop.png -o rooftop.png` | `pixel-cat convert bob.gif -o bob.gif --mode grid --grid 96 --sampling crisp --colors 16` |
  93. </div>
  94. The stills above came out of one command each, with no settings chosen by hand. pixel-cat is plain Python with numpy and Pillow, and it makes no network calls. A conversion takes a fraction of a second.
  95. | Mode | What it does |
  96. | --- | --- |
  97. | `recommended` | Reads the picture and chooses the grid, the sampler, the number of colors and the cleanup. `--contrast` reduces the picture to its few big shapes. |
  98. | `grid` | You set the longest side in cells, or `native` to keep the size. Four samplers decide what a cell shows: the pixel under its center (`exact`), the average of its area (`area`), its dominant color (`crisp`), or its dominant color with thin dark outlines kept (`ink`). |
  99. | `faithful` | Samples on a regular grid of `--pixel`-sized cells and maps to the source colors, a named palette or your own colors. |
  100. | `artist` | Smooths areas of similar brightness, lifts the saturation and snaps to a palette. `--strength` sets how far regions merge. |
  101. Reducing colors follows the crowd, so a small red scarf in a blue picture can turn blue. pixel-cat checks for that: a small area with a color of its own keeps a palette entry. `--symmetry left` or `right` mirrors one half onto the other. `--palette` takes `source`, one of the 23 names from `pixel-cat catalog` (4 to 64 colors), or a comma-separated list of `#RRGGBB` colors.
  102. Animations convert frame by frame and share one palette. Still areas would flicker, because each frame rounds a little differently. A cell that barely changes over the whole loop is therefore held at one color (`--stability`, 0 switches it off), and real motion is left alone. `pixel-cat check walk.gif` looks for flicker, stray fragments and holes and names the areas where they gather. When one spot flickers next to motion you want to keep, `--hold x,y,width,height` makes just that area stand still. `--frames` thins an animation out, `--speed` changes its pace, `--frame` exports a single frame as PNG.
  103. Converted art has hard edges: a cell is solid or empty. `--alpha soft` keeps the transparency of a shadow or a glow, and its colors still come from the palette, so a soft rim cannot smuggle colors past the limit. PNG and video outputs are enlarged to a size that is easy to look at. Pass `--scale 1` for one file pixel per cell.
  104. ## Sprites
  105. <div align="center">
  106. ![A potion icon on a paper background becomes a 44 by 64 sprite with a transparent background and an outline](media/potion-sprite.png)
  107. </div>
  108. ```sh
  109. uv run pixel-cat convert icon.png -o sprite.png --mode grid --grid 64 --sampling ink --colors 12 --cutout --trim --outline "#101018"
  110. ```
  111. `--cutout` makes the background transparent, `--trim` crops to the drawing and `--outline` draws a rim around it. A recipe has more finishing steps under `edits`: pad, flip, shift, replace a color, clean specks, thin lines to one cell and close breaks in them, remove halos beside lines and loose bits at the edge. [Finishing steps](docs/recipes.md#edits)
  112. ## Loops from a still
  113. <div align="center">
  114. ![The lake picture as a loop: the clouds drift and the water ripples](media/lake-loop.gif)
  115. </div>
  116. A still picture can become a seamless loop. Name the regions and what moves in them: `clouds` drift, `water` ripples, `twinkle` makes small lights blink, `sway` moves leaves and grass, `rise` lifts smoke. These only move cells that are already there, so the palette stays. `fireflies`, `leaves` and `birds` add small things of their own. The last frame leads back into the first. In the studio, "Loop" lets you paint each area on the picture.
  117. ```sh
  118. uv run pixel-cat convert examples/images/lake.png -o output/lake.gif --loop clouds,water
  119. uv run pixel-cat run examples/recipes/lake-loop.json
  120. ```
  121. The first command guesses the sky and the water. The guess is rough, and here it takes the bright mountains for sky. The recipe draws both areas as polygons instead, which is what an agent does after one look at the picture. [Loop settings](docs/recipes.md#loop)
  122. ## Make a film
  123. Give an agent in this checkout a subject and name the skill. Try “Use `pixel-cat-film` to make a 15-second portrait film about a lighthouse keeper winding a clockwork sun. Give the winding key a sound I can recognize in the dark.” The skill shows how to plan four shots, move a subject between keyframes, review every moving part on enlarged sheets and export a README preview. [Agent skill](.agents/skills/pixel-cat-film/SKILL.md)
  124. With the [installed skill](#install-as-an-agent-skill), ask from any folder. The agent follows the same film skill in its pixel-cat checkout and writes the film to your folder.
  125. To render *Tide Bell* from the included PNGs and scene file, run this from the checkout with FFmpeg on your PATH.
  126. ```sh
  127. uv run python .agents/skills/pixel-cat-film/scripts/render.py \
  128. examples/films/tide-bell/story.json output/tide-bell.mp4
  129. ```
  130. ## Verify
  131. ```sh
  132. uv run python -m unittest discover -s tests -v
  133. ```
  134. The tests build their own inputs and check what a conversion promises: the grid size, the color limit, palette membership, kept outlines, restored pixel grids, mirrored halves, steady still areas in a loop, and the frame counts and timings of GIF, sprite-sheet and video jobs, loops that close without a jump, the film camera, lifted props, project files and the studio's server. A few press the studio's page in a browser without a window, with real pointer input; they are skipped where no such browser is installed.
  135. ## License
  136. [MIT](LICENSE)
  137. [license-shield]: https://img.shields.io/badge/license-MIT-2f7d5b?style=flat-square
  138. [license-url]: LICENSE
  139. [python-shield]: https://img.shields.io/badge/python-3.11%2B-3776ab?style=flat-square&logo=python&logoColor=white
  140. [python-url]: pyproject.toml
  141. [version-shield]: https://img.shields.io/badge/version-0.6.5-6b5fb5?style=flat-square
  142. [version-url]: pyproject.toml
  143. [exports-shield]: https://img.shields.io/badge/exports-PNG%20%C2%B7%20GIF%20%C2%B7%20MP4%20%C2%B7%20WebM-c9682c?style=flat-square
  144. [exports-url]: docs/recipes.md
  145. [skill-shield]: https://img.shields.io/badge/npx%20skills%20add-pyros--projects%2Fpixel--cat-111111?style=flat-square
  146. [skill-url]: #install-as-an-agent-skill
  147. [offline-shield]: https://img.shields.io/badge/runs-offline-4a8f9c?style=flat-square
  148. [offline-url]: #start

Ratings and comments

Sign in to rate this skill.

Sign in

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