🪶 Github Scribe

Prints out a small image into the contributions graph of a GitHub profile.

Getting Started

This tool works by creating commits in a git repo. To use it, you'll need your own repo to commit to:

• Fork this repo, or
• Create a new repo and clone it locally

The commits will appear on your GitHub contribution graph once pushed.

Setup

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Usage

python3 main.py --image <path> --start-date <YYYY-MM-DD> [options]

Required Arguments

Argument	Short	Description
--image	-i	Path to source image (7px tall, black/white only)
--start-date	-s	Start date in YYYY-MM-DD format (must be a Sunday)

Optional Arguments

Argument	Short	Default	Description
--commits-per-pixel	-c	220	Commits per dark pixel
--commits-per-blank	-b	0	Commits per blank pixel
--dry-run	-n	false	Preview without making commits

Examples

Dry run to preview:

python3 main.py --image ./images/image1.png --start-date 2025-08-17 --dry-run

Run with custom commit intensity:

python3 main.py -i ./images/image1.png -s 2025-08-17 -c 150

Notes

• The source image should be exactly 7 pixels in height (one row per day of the week)
• The image should only contain black or white pixels
• The start date must be a Sunday (first row of the contributions graph)
• Accounts with many existing commits may need a higher --commits-per-pixel value for the image to be visible
• Before running, an ASCII preview of the image and settings summary will be displayed
• You will be prompted to confirm before commits are made

Demo

screencap.mp4