streakboard

README

streakboard

A GitHub-style contribution board ("commit board") you feed with your own per-day activity data — habits, vocabulary reviews, anything countable. Renders to a PNG and embeds in Bubble Tea TUIs as a real pixel image via the Kitty graphics protocol (Ghostty and kitty).

Bubble Tea component

board := tui.New(entries, streakboard.Options{Max: 20, Scale: 3})
// route Update messages to it, put board.View() in your layout,
// and sequence board.Close() before tea.Quit.

The board sizes itself to the terminal (two columns per week, up to a year) and is ordinary text to Bubble Tea: Unicode placeholder cells the terminal overlays with the image, so it scrolls and composes like any view content. GitHub-style month and weekday labels are composed around the image as dimmed text in the terminal's own font. Image bytes travel out-of-band as tea.Raw commands. Needs bubbletea v2 and a TrueColor profile (tea.WithColorProfile).

Try it in Ghostty: go run ./cmd/streakboard-demo (t cycles themes, n regenerates data, q quits).

Package kitty underneath is framework-agnostic and stdlib-only: TransmitPNG / Place / Placeholder / Delete, if you want to integrate without Bubble Tea.

Library

entries := []streakboard.Entry{
	{Date: time.Now(), Count: 12}, // 12 vocab words reviewed today
}
img := streakboard.Render(entries, streakboard.Options{
	Max:     20, // 20+ per day = full intensity; 0 scales to the best day
	Palette: streakboard.CatppuccinMocha,
})
// img is an *image.NRGBA on a transparent background

Palettes: GitHubDark (default), GitHubLight, and the four Catppuccin flavors CatppuccinLatte, CatppuccinFrappe, CatppuccinMacchiato, CatppuccinMocha — or bring your own Palette (five color.NRGBA values, level 0 through 4).

Options zero value shows the last 365 days ending today, dark theme, at 2x GitHub's native geometry (10px cells, 3px gaps, 2px radius). From/ To pick a different window; missing days render as empty (level 0) cells, and same-day entries are summed. Counts bucket into levels 1-4 relative to Max, like GitHub's quartiles.

CLI

Reads YYYY-MM-DD COUNT lines from stdin:

go run ./cmd/streakboard -max 20 -o board.png < activity.txt
kitty +kitten icat board.png

Flags: -o output path, -scale N, -max N, and -theme with github, github-light, catppuccin (mocha), catppuccin-latte, catppuccin-frappe, catppuccin-macchiato, or catppuccin-mocha.

Documentation

Overview

Package streakboard renders GitHub-style contribution boards from arbitrary per-day activity data — habits, vocabulary reviews, anything countable.

Index

• Variables
• func Render(entries []Entry, o Options) *image.NRGBA
• type Entry
• type Options
• type Palette

Variables

var (
	GitHubDark  = Palette{hex(0x161b22), hex(0x0e4429), hex(0x006d32), hex(0x26a641), hex(0x39d353)}
	GitHubLight = Palette{hex(0xebedf0), hex(0x9be9a8), hex(0x40c463), hex(0x30a14e), hex(0x216e39)}
)

GitHub's contribution-graph greens.

var (
	CatppuccinLatte     = ramp(hex(0xccd0da), hex(0xeff1f5), hex(0x40a02b))
	CatppuccinFrappe    = ramp(hex(0x414559), hex(0x303446), hex(0xa6d189))
	CatppuccinMacchiato = ramp(hex(0x363a4f), hex(0x24273a), hex(0xa6da95))
	CatppuccinMocha     = ramp(hex(0x313244), hex(0x1e1e2e), hex(0xa6e3a1))
)

Catppuccin flavors (https://catppuccin.com/palette): empty cells use the flavor's surface0, active levels blend from base toward its green.

Functions

func Render

func Render(entries []Entry, o Options) *image.NRGBA

Render draws one rounded square per day in [From, To] — one column per Sunday-anchored week — on a transparent background. Days without entries are drawn at level 0; positive counts are bucketed into levels 1-4 relative to Max, like GitHub's quartiles.

Types

type Entry

type Entry struct {
	Date  time.Time // only the calendar date (in Date's own location) is used
	Count int
}

Entry records activity on one day. Multiple entries for the same calendar date are summed.

type Options

type Options struct {
	Palette Palette   // colors for levels 0-4; zero value means GitHubDark
	Scale   int       // multiplier over the native geometry; <1 means 2
	From    time.Time // first day shown; zero means 364 days before To
	To      time.Time // last day shown; zero means today
	Max     int       // count drawn at full intensity; <1 means the highest count in range
}

Options control Render. The zero value shows the last 365 days ending today, GitHub dark theme, at 2x GitHub's native geometry (10px cells, 3px gaps, 2px corner radius).

type Palette

type Palette [5]color.NRGBA

Palette holds the cell colors for intensity levels 0 through 4.