gh-chart

Generate a GitHub contribution chart image from the command line.

Install

# Clone and install
git clone https://github.com/griffinwork40/gh-chart.git
cd gh-chart
pip install -e .

# Or just run directly
python3 gh_chart.py

Prerequisites

• GitHub CLI (gh) authenticated (gh auth login)
• Python 3.10+
• matplotlib, pillow (pip install -r requirements.txt)

Usage

# Your own chart (uses authenticated gh user)
gh-chart

# Specific user
gh-chart torvalds

# Light theme
gh-chart --theme light

# Custom output path
gh-chart -o my-contributions.png

# Print stats
gh-chart --stats

# Stats as JSON (pipe to jq, post to APIs, etc.)
gh-chart --json

# Render and open immediately
gh-chart --open

Options

Flag	Description
username	GitHub username (default: authenticated user)
-o, --output PATH	Output PNG path (default: gh-chart-<user>.png)
--theme dark|light	Color theme (default: dark)
--stats	Print contribution stats to stdout
--json	Output stats as JSON
--open	Open image after rendering (macOS/Linux)

Example JSON output

{
  "username": "griffinwork40",
  "total": 12245,
  "max_day": 282,
  "max_date": "2025-12-28",
  "max_streak": 83,
  "active_days": 354,
  "daily_avg": 33.5
}

AFK Skill

This repo includes an agent-afk skill. Install it:

# Symlink into your AFK skills directory
ln -s /path/to/gh-chart ~/.afk/skills/gh-chart

Then use it in any AFK session:

/gh-chart              # your chart
/gh-chart torvalds     # someone else's

License

MIT