GreenWall: Painting on Your GitHub Contribution Graph with a Desktop App

What GreenWall Solves and Who It Is For

GreenWall addresses a niche but persistent desire: making the GitHub contribution graph look like something other than a random scatter of green squares. The graph is a public record of your commit activity, and for many developers it is a de facto visual resume. GreenWall lets you upload an image, convert it into a pattern of contribution levels, and then automates the creation of a repository whose commit history produces that pattern. The intended audience is developers who want a personalized profile, hobbyists experimenting with GitHub's API, and anyone curious about how contribution graphs work. It is not a productivity tool. It is a toy, but a well-executed one, and the README is explicit that it exists for educational and demonstration purposes, not for deceiving recruiters.

How It Works: From Image to Contribution Heatmap

The core mechanism is a desktop application built with Wails, which combines a Go backend with a web frontend. You start by uploading an image, either PNG, JPG, or SVG. The app then maps the image's pixels to a grid that matches GitHub's contribution calendar: rows from 1 to 7 (days of the week) and columns from 1 to 52 (weeks of the year). You choose a mode: Auto for photos and grayscale images, or Binary for black-on-white text or line art. In Binary mode, each cell is either filled or not, while Auto mode presumably maps pixel intensity to different shades of green. The README mentions fine-tuning controls like brightness invert, threshold, scaling filter, and stroke recovery. Once the pattern is generated, you see it on a calendar view. You can drag across the calendar to paint or erase cells, adjust brush intensity for different green shades, and even copy and paste sections of the pattern. When you are satisfied, you click "Create Remote Repo", edit the repo name and description, choose public or private, and then "Generate & Push" creates a repository on your GitHub account and pushes commits that correspond to the pattern. The app handles the grunt work of generating commit dates and amounts.

Getting It Running: Commands and Platform Quirks

The README is light on installation details for end users, saying only to download the app and run it. For developers, the setup is more concrete. You need Go 1.24 or later, Node.js v22 or later, and Git. You install the Wails CLI with `go install github.com/wailsapp/wails/v2/cmd/wails@v2.10.2`. Then clone the repository, `cd` into it, and run `cd frontend && npm install` to install front-end dependencies. The development environment starts with `wails dev`, and you build a production binary with `wails build`, which outputs to `build/bin/`. On macOS, the app is not signed, so the first launch may be blocked by Gatekeeper. The README provides two commands to fix this: `sudo xattr -cr ./green-wall.app` and `sudo xattr -r -d com.apple.quarantine ./green-wall.app`. It advises trying them in order and stopping once one works. Note that these commands do not launch the app; you must double-click it manually. On Windows and Linux, you can run the app directly, but there is no mention of code signing or antivirus warnings, which is a gap in the documentation.

The Fine-Tuning Controls and Modes

The image conversion is not a one-click magic. The README includes a quick guide table that maps common input types to recommended settings. For black text on white background, it suggests Binary mode, invert on, smoothing set to Nearest, threshold between 0 and 10, recovery 1 between 12 and 24, and dilation 0 to 1. For low-contrast photos, Auto mode with Bilinear smoothing and threshold 0 to 15 works better. Very thin lines, two pixels or less, need Binary mode, invert on, Nearest smoothing, recovery 1 from 20 to 28, and dilation 1 to 2. Bright or noisy photos benefit from Auto mode, Bilinear smoothing, and a higher threshold of 5 to 20. These parameters directly affect how the final heatmap looks, and the README offers tips: use "Target rows" to keep tall images from being flattened, and if Binary mode looks too empty, increase stroke recovery or add dilation. This level of control is useful, but it also means you will need to experiment. The README does not explain what each parameter does in detail, so expect a trial-and-error phase.

A Real Limitation: The Rendering Delay and Private Repo Caveat

The most important limitation is the delay between pushing the repository and seeing the contributions on your profile. The README states that GitHub may take anywhere from 5 minutes to 2 days. That is a wide window, and it makes the tool unsuitable for anyone who needs immediate visual feedback. If you are planning a design for a specific date, you must push well in advance. The README also suggests keeping the repository private and enabling "Include private contributions" in your profile settings. That way, others cannot see the repo content, but the contribution streak still counts. This is a clever workaround, but it has a side effect: if you later make the repo public, the commit history will reveal the pattern's source. Another limitation is that the app only works with GitHub, not other platforms like GitLab or Bitbucket, and it requires a Personal Access Token with sufficient permissions to create repositories and push commits. The README does not specify which scopes are needed, so you may need to experiment.

Alternatives and Why They Differ

The obvious alternative is to script the process manually using the GitHub API or a tool like `git` with crafted commit dates. You could write a shell script that creates commits with specific timestamps and pushes them to a repository. That approach gives you full control and does not require installing a desktop app, but it is far more tedious. You would need to calculate the exact dates for each cell, generate the appropriate commit counts, and handle the push. Another alternative is a web-based service like `github-contribution-graph` or similar, but these require you to upload an image and then generate a repository on the server's behalf, which raises security concerns because you are giving a third party your GitHub token. GreenWall keeps the token local, which is a privacy advantage. The key difference is that GreenWall is a local desktop app, so your token never leaves your machine, whereas web services require you to trust the server. The trade-off is that you must download and run an unsigned binary, which carries its own risks.

Maintenance and Upgrade Cost

The project is actively maintained, with the latest release v0.7.5 pushed on March 28, 2026, and previous releases in January and December 2025. The language is TypeScript, but the backend is Go, so maintenance involves both ecosystems. The development guide requires specific versions of Go and Node.js, which means you need to keep those toolchains up to date. The Wails CLI version is pinned to v2.10.2, but you can update it as needed. The README does not mention any upgrade path for existing users, so you may need to rebuild the app from source to get the latest features. The license is MIT, so you are free to modify and redistribute the code, but the project does not provide a formal contribution guide beyond the development setup. The star history section and the mentions of being featured in newsletters suggest a community following, but the README does not include a changelog, so you will need to check the release notes on GitHub to understand what changed between versions.

Editorial conclusion

Adopt GreenWall if you want a visual, interactive way to create custom contribution graphs without manually scripting commit dates. It is ideal for hobbyists and developers who enjoy personalizing their GitHub profile. Avoid it if you need instant results, as GitHub can take from 5 minutes to 2 days to display contributions, and note that the app is unsigned on macOS, requiring manual quarantine removal. Before using, verify your Personal Access Token has the correct scopes for creating and pushing repositories, and be aware that the project's disclaimer places responsibility on you for any misuse, such as falsifying job applications. The app is MIT-licensed, so you can inspect and modify the code, but the desktop binaries are not signed, so weigh the security implications of running unsigned software.

Official sources

1. Official README
2. Project repository
3. Release notes