GitHub Grid Editor

Paint your GitHub contribution graph with backdated commits — interactively or from the command line.

Features

• Interactive TUI — visual grid editor powered by Bubble Tea; navigate, paint, and generate without touching the CLI
• Headless mode — fully scriptable via flags for automation and AI agent use
• Load any user's graph — fetch a GitHub user's existing contribution history as a starting baseline
• Year selection — target any calendar year (2005–present) or use the default rolling 52-week window
• Flexible exclusions — skip weekends, weekdays, specific days, or entire months
• Randomize — fill non-excluded days with random commit counts in a configurable range
• Pinpoint overrides — set exact commit counts for specific dates or by cell index
• Pattern painting — use --set-cells to paint arbitrary pixel patterns on the graph
• Push to GitHub — push the generated repo directly from the tool or TUI
• Custom git identity — override the author name and email per-run
• Grid preview — print the contribution grid before writing anything with --show-final-dashboard
• Claude Code skill — install as a /github-grid-editor skill for AI-assisted graph painting

Installation

Download a prebuilt binary from the GitHub Releases page:

1. Download the latest archive for your machine (amd64 or arm64)
2. Extract it
3. Move github-grid-editor somewhere on your PATH, such as /usr/local/bin

chmod +x github-grid-editor
mv github-grid-editor /usr/local/bin/

Then run:

github-grid-editor

Install with go install:

go install github.com/DKSadx/github-grid-editor@latest

Make sure your Go bin directory is on PATH:

export PATH="$(go env GOPATH)/bin:$PATH"

Or build from source:

git clone https://github.com/DKSadx/github-grid-editor
cd github-grid-editor
go build -o github-grid-editor .

Then run it directly:

./github-grid-editor

Release Workflow

The repository includes a Makefile for local builds, cross-platform binaries, archives, and GitHub releases.

# Run the full flow: build, package, checksum, and create a GitHub release
make publish

# Build the local binary
make build

# Cross-build for macOS, Linux, and Windows into dist/
make build-all

# Build and package release archives into dist/
make archives

# Build archives and generate dist/checksums.txt
make checksums

# Print the default next release tag
make print-tag

# Create a GitHub release with the default auto-incremented tag
make release

# Override the tag manually when needed
make release TAG=v1.4.0

# One-command release with a manual tag override
make publish TAG=v1.4.0

Auto tag behavior:

• If there are no existing semver tags, make release uses v0.1.0
• Otherwise it bumps the minor version by 0.1.0
• Example: v0.1.0 becomes v0.2.0, v1.3.0 becomes v1.4.0

Requirements:

• gh must be installed and authenticated with gh auth login
• zip, tar, and shasum must be available in PATH

Usage

github-grid-editor [flags]
github-grid-editor <command> [flags]

Running with no flags opens the interactive TUI.

Source flags

Flag	Description	Default
-u, --user <username>	Load a GitHub user's contribution graph as a baseline
-p, --path <dir>	Git repository where commits are written (omit to be prompted for current directory)
--year <N>	Target calendar year (2005–present); omit for rolling 52-week window ending today
--git-name <name>	Git author name for commits	from ~/.gitconfig
--git-email <email>	Git author email for commits	from ~/.gitconfig

Operations

Applied in order: exclusions → randomize → set-date → set-cells

Flag	Description	Default
--exclude-days <days>	Skip days: sun mon tue wed thu fri sat or weekend/weekday
--exclude-months <months>	Skip months: jan feb mar apr may jun jul aug sep oct nov dec
--randomize	Assign random commit counts to all non-excluded days
--min <n>	Minimum commits per day (with --randomize)	1
--max <n>	Maximum commits per day (with --randomize)	50
--set-date <spec>	Exact counts: YYYY-MM-DD=N[,YYYY-MM-DD=N,…]
--set-cells <spec>	Exact counts by cell index: idx:count[,…] where idx = col*7+row

Output flags

Flag	Description
--generate	Write commits to the repository
--show-final-dashboard	Print the contribution grid after applying all operations; can be combined with --generate
--push	Push to GitHub after generating (prompts for remote URL if not set)

Meta flags

Flag	Description
--headless	Run without opening the TUI
--help	Show help
--no-prompt	Suppress interactive prompts; intended for AI agents and CI
--skills	Print JSON skills manifest and exit

Subcommands

Command	Description
install	Install as a Claude Code skill (~/.claude/skills/github-grid-editor/SKILL.md)

Examples

The repository includes a set of example scripts in examples/.

Note: these examples were inspired by contribution-graph art and patterns shared on the internet, then adapted into runnable scripts for this project.

# Open the interactive TUI
github-grid-editor

# Preview bundled examples
./examples/pacman.sh
./examples/space-invader.sh
./examples/cat.sh

# Generate a bundled example
REPO_PATH=/tmp/pacman-graph GIT_EMAIL=you@example.com ./examples/pacman.sh --generate

# Preview random commits on weekdays (no writes)
github-grid-editor --randomize --exclude-days weekend --show-final-dashboard

# Preview the final grid, then generate in the same run
github-grid-editor --randomize --exclude-days weekend --show-final-dashboard --generate

# Generate random commits, skip weekends
github-grid-editor --randomize --exclude-days weekend --generate

# Controlled density, skip December
github-grid-editor --randomize --min 5 --max 15 --exclude-days weekend --exclude-months dec --generate

# Load an existing user's graph, then boost it
github-grid-editor --user DKSadx --randomize --min 1 --max 10 --generate

# Pin specific dates to zero
github-grid-editor --set-date 2025-12-25=0,2026-01-01=0 --generate

# Paint a pattern using cell indices (col*7+row)
github-grid-editor --user DKSadx --set-cells "70:30,77:30,84:30" --show-final-dashboard

# Target a specific year
github-grid-editor --year 2023 --user DKSadx

# Write commits to a custom repo path
github-grid-editor --randomize --exclude-days weekend --path ~/my-contrib-repo --generate

# Generate and push in one step
github-grid-editor --randomize --exclude-days weekend --path ~/my-contrib-repo --generate --push

# Use a custom git identity
github-grid-editor --randomize --git-name "Ada Lovelace" --git-email "ada@example.com" --generate

Full example docs: examples/README.md

Example Gallery

cat.sh

Cat pixel art traced cell-by-cell from a GitHub graph screenshot.

./examples/cat.sh
REPO_PATH=/tmp/cat-graph GIT_EMAIL=you@example.com ./examples/cat.sh --generate

ecg.sh

ECG / heartbeat waveform traced cell-by-cell from a contribution graph screenshot.

./examples/ecg.sh
REPO_PATH=/tmp/ecg-graph GIT_EMAIL=you@example.com ./examples/ecg.sh --generate

equalizer.sh

Sound equalizer with irregular bar heights across the grid.

./examples/equalizer.sh
REPO_PATH=/tmp/equalizer-graph GIT_EMAIL=you@example.com ./examples/equalizer.sh --generate

mascots.sh

Pixel art mashup with Octocat, a Mario mushroom, and a small cat.

./examples/mascots.sh
REPO_PATH=/tmp/mascots-graph GIT_EMAIL=you@example.com ./examples/mascots.sh --generate

mondrian.sh

Mondrian-style contribution graph composition traced from a screenshot.

./examples/mondrian.sh
REPO_PATH=/tmp/mondrian-graph GIT_EMAIL=you@example.com ./examples/mondrian.sh --generate

nature-landscape-background.sh

Nature landscape with mountain shapes and a filled ground/background.

./examples/nature-landscape-background.sh
REPO_PATH=/tmp/nature-graph GIT_EMAIL=you@example.com ./examples/nature-landscape-background.sh --generate

pacman.sh

Pac-Man pixel art traced cell-by-cell from a contribution graph screenshot.

./examples/pacman.sh
REPO_PATH=/tmp/pacman-graph GIT_EMAIL=you@example.com ./examples/pacman.sh --generate

pixel-art.sh

Reference pixel-art composition traced cell-by-cell from a contribution graph screenshot.

./examples/pixel-art.sh
REPO_PATH=/tmp/pixel-art-graph GIT_EMAIL=you@example.com ./examples/pixel-art.sh --generate

ships.sh

Two ships pixel art traced cell-by-cell from a contribution graph screenshot.

./examples/ships.sh
REPO_PATH=/tmp/ships-graph GIT_EMAIL=you@example.com ./examples/ships.sh --generate

space-invader.sh

Three Space Invaders distributed across the contribution graph.

./examples/space-invader.sh
REPO_PATH=/tmp/space-invader-graph GIT_EMAIL=you@example.com ./examples/space-invader.sh --generate

waves.sh

Ocean wave pattern with repeated sinusoidal crests across the year.

./examples/waves.sh

After generating

Generation only works with an empty or non-existent local repo path. If --path already contains commits, the tool exits instead of modifying history.

The tool prints push instructions when it finishes:

cd "/path/to/repo" && git remote add origin <your-repo-url> && git push -u origin main

Create an empty repo on GitHub first (no README, no .gitignore), then paste the command above with your repo URL. Or use --push / press P in the TUI to push directly.

TUI keybindings

Key	Action
h/j/k/l or arrows	Move cursor
+ / =	Increment commit count
-	Decrement commit count
s	Enter exact commit count
r	Randomize current cell (1–50)
R	Randomize all cells (1–50)
X	Toggle day/month exclusions popup
c	Clear all commits
e	Open export command view
g	Generate commits
P	Push to GitHub
I	Set git author identity
y	Change year
Esc Esc	Cancel in-progress generation
q / Ctrl+C	Quit

Export command

Press e in the TUI to open an export view with a reproducible github-grid-editor command for the current edits.

• The export includes context like --user, --path, --year, and git identity when set
• --set-cells is exported as additive deltas over fetched GitHub counts, so replaying the command reproduces the same final graph
• Press c in the export view to copy the command to the clipboard

Coordinate system (--set-cells)

The grid is 7 rows × 52 columns (up to 53 for year mode):

• Row 0 = Sunday, Row 6 = Saturday
• Col 0 = oldest week (leftmost on GitHub), Col 51 = most recent week

idx = col * 7 + row

Use larger counts for brighter pixels. In the bundled pixel-art example, 5, 15, 30, and 50 map to the four visible green intensity levels.

Claude Code skill

Install as a Claude Code skill to paint your graph with natural language:

github-grid-editor install

Then inside Claude Code:

/github-grid-editor fill weekdays with random commits, skip december

For automation or agent use outside the TUI, combine --headless with --no-prompt to avoid interactive prompts.

Requirements

• Go 1.25+
• Git (must be in PATH)
• A GitHub account with a public contributions graph (for --user loading)

License

MIT