Building gittui - A GitHub Profile Viewer in the Terminal

Why Though

I wanted to check GitHub profiles from the terminal. That's it. That's the whole reason.

Also I was learning Go and Bubble Tea and needed a project that wasn't just another todo app. Something with real API calls, real data, and enough complexity to teach me things.

The First Version

Started simple - fetch a GitHub profile, display it in the terminal. Bubble Tea makes this surprisingly straightforward if you think in terms of Model-Update-View.

The model holds your state, Update handles messages (like API responses or key presses), View renders everything. It's the Elm Architecture and it just works.

type model struct {
    username string
    profile  GitHubProfile
    loading  bool
}

Hit the GitHub API, parse the JSON, render some stats. First version probably took an evening.

Then It Got Complicated

"Hey, what if we showed contribution graphs?"

"What about colorizing the avatar based on the theme?"

"We should support multiple themes so people can pick their colors"

That last one is what spiraled into building the whole gogh-themes package (see my other post about that).

But before that, I hardcoded like 3 themes into gittui. It worked but it was ugly. Every time I wanted to add a theme I was copying and pasting color definitions. The code was getting gross.

The Theme Refactor

Once I had gogh-themes built (361 themes as a proper package), I went back to gittui with a mission: zero hardcoded themes.

The refactor was pretty satisfying:

• Ripped out all the hardcoded theme functions
• Deleted the entire themes/ directory (361 YAML files gone)
• Deleted theme_loader.go (163 lines of theme loading logic)
• Added one import: github.com/willyv3/gogh-themes

Total change: -10,083 lines

The app got cleaner and suddenly had 361 professional themes instead of my janky 3.

Security Stuff We Had to Fix

Building a TUI that makes API calls taught me some things about security:

Validate everything from the API. Just because GitHub's API is trustworthy doesn't mean your parsing code is perfect. Handle nil pointers, validate data structures, don't assume anything.

What We Learned

Bubble Tea Patterns

• Spinner during API calls - Users need to know something's happening
• Error handling - Show errors in the UI, don't just panic
• Window resize handling - Terminals resize, your TUI needs to handle it
• Key bindings - Make them obvious, show help text

GitHub API Stuff

• Rate limiting is real - Authenticated requests get you way more
• Response shapes vary - User profiles vs org profiles have different fields
• Null values everywhere - People don't fill out their profiles completely

Go Specific

• Structs for everything - Type safety is your friend
• Pointer receivers for methods - Especially when mutating state
• Error handling - if err != nil gets repetitive but it's clear
• Testing - Write tests before shipping

Project Hygiene

• Don't Repeat Yourself - If you're copying code, you need a function or package
• Release automation - Manual releases are error-prone
• Git history matters - Clean commits, meaningful messages
• README first - Write docs as you build, not after

The Current State

gittui v1.0.1 is out there. It works. You can:

• View any GitHub profile from the terminal
• See contribution graphs
• Cycle through 361 themes
• Read the stats without leaving your terminal

It's not going to replace the GitHub web UI but that was never the point. The point was learning Go, understanding Bubble Tea, and building something that works.

Also the contribution graph rendering in ASCII is kind of sick.

Would I Do It Again?

Yeah, absolutely. Building gittui taught me more about Go and TUI development than any tutorial would have.

The theme management problem it created led to building gogh-themes, which turned into a whole thing on its own.

Sometimes you start a project to solve one problem and end up solving a different one entirely. That's kind of how open source works.

Links

• GitHub: https://github.com/willyv3/gittui
• gogh-themes: https://github.com/willyv3/gogh-themes
• Bubble Tea: https://github.com/charmbracelet/bubbletea