snk

Snk is a tool that turns a GitHub user's contribution graph into a snake game animation. The contribution graph is the grid of colored squares on a GitHub profile page, where each square represents a day and its color shows how many contributions were made that day. Snk reads that grid, computes a path where a snake travels through and eats each colored square in order, then exports the result as an animated SVG or GIF file.

The most common use is as a GitHub Action. You add it to a workflow in your repository, provide your GitHub username, and it generates an animated image of the snake moving across your contribution grid. The action can run on a schedule, so the image is regenerated daily with fresh data. The resulting file can then be embedded in a GitHub profile README, which is the custom page displayed when someone visits your GitHub profile.

Several output options are available. SVG files load faster and a dedicated svg-only variant of the action skips GIF generation entirely. GIF files support a custom background color. Colors for the dots, the snake body, and the background can all be set independently, and preset palettes are provided for light and dark GitHub themes. Dark mode is supported through a standard HTML picture element that switches between two image sources based on the viewer's theme.

The tool is also published as an npm package called generate-snake-animation. This allows you to call it from JavaScript or TypeScript code directly, or run it via npx from the command line. It supports GitHub, GitLab, and Forgejo, the platform used by Codeberg.

The project does not accept pull requests. Issues and bug reports are welcome, but proposed changes to the API or implementation are expected to be discussed in an issue first.