hjr265 recently published a write-up about building GitTop, a terminal viewer for git repository activity modeled on htop, using a fully agentic coding workflow where an LLM agent handled implementation end to end. The tool shipped. The author calls it their first fully agentic project.
The specification is what I keep coming back to. “Show git activity like htop shows processes” is six words that carry a substantial design load. For agentic coding, the quality of the initial specification is the most direct lever the developer has on output quality, and this particular specification is unusually dense for its length.
The Gap in the Git TUI Landscape
Before examining the specification, it helps to establish that GitTop fills a genuine gap. The git TUI ecosystem is not sparse: tig is a mature ncurses browser for git history written in C; lazygit is a comprehensive Go-based TUI for performing git operations; gitui is a Rust-based staging and commit client. All three are actively maintained and widely used.
None of them are live activity monitors. tig shows history you navigate through, with manual refresh via a key press. lazygit is oriented around performing operations on a repository, staging files, writing commit messages, managing branches, rather than observing commit activity as it accumulates. gitui is similar. The htop-style continuously refreshing display of recent git commits, one that polls at a fixed interval and surfaces who is committing what in real time, does not have a well-established existing representative.
This means hjr265 was specifying something genuinely new, with no obvious existing implementation to point at. The specification burden could have been high. That it resolved into a coherent tool with minimal design friction is largely attributable to the reference class.
What the htop Reference Encodes
htop was first released in 2004 by Hisham Muhammad as an improvement on the original top command, which dated to the early 1980s. Where top produced a static, flickering display suited for batch output, htop introduced a full-screen interactive interface: color-coded CPU and memory meters, per-core bars, a scrollable process list with keyboard navigation, and a function-key action bar at the bottom. The interactive monitor genre it established has been reproduced widely: iftop for network traffic, iotop for disk I/O, ctop for containers, k9s for Kubernetes, bottom as a general system monitor in Rust.
When you say “like htop,” you communicate a bundle of design decisions without enumerating them:
- Refresh semantics: continuous polling at a fixed interval, not on-demand.
- Interaction model: keyboard navigation, column-based sorting via shortcut keys, action on selected items.
- Layout conventions: header meters at the top, a scrollable list below, a function-key legend at the bottom.
- Information density: columns, numbers, color as signal. Dense by design, not sparse.
- User persona: a practitioner who already understands the domain. No tutorial mode, no onboarding.
- Scope: local, single-instance, no daemon required, no external service.
The reference also communicates by exclusion. htop does not have a configuration file, an export function, a web interface, or an onboarding wizard. “Like htop” therefore excludes those things from scope without the developer needing to state it. For a specification driving an agentic workflow, what is excluded is as valuable as what is included. Fewer ambiguous decisions means fewer revision cycles where the agent fills a gap with a choice the developer did not intend.
Why Reference-Class Specs Work in Agentic Workflows
The output quality of a fully agentic workflow is closely tied to the ambiguity left in the initial specification. When requirements leave significant decisions open, the agent makes choices based on training data priors rather than the developer’s actual intent. Each mismatch requires a correction cycle. The number of correction cycles largely determines whether the agentic approach saved time relative to direct implementation.
A reference-class specification reduces initial ambiguity without requiring the developer to enumerate every decision. An LLM trained on substantial programming and Unix tooling documentation has reliable representations of htop’s design conventions. Given “like htop,” the agent can derive reasonable defaults for refresh interval, column layout, scroll behavior, and keyboard shortcut conventions from the reference, rather than needing explicit guidance on each.
This works in human development too: “build something like X” front-loads shared understanding and saves documentation effort. The difference in agentic workflows is the mechanism. A human developer understands the shorthand and can ask clarifying questions about the parts that do not transfer cleanly. An agent extracts implicit decisions from training priors; the denser and more consistent those priors, the more reliably the shorthand transfers. htop’s design is well-documented and widely reproduced across dozens of tools, which means the training signal is dense and coherent. A more obscure or internally-designed reference tool carries substantially less weight.
Where the Reference Class Falls Short
The htop analogy resolves visual conventions and interaction behavior but leaves the data model semantics open. htop monitors a running system: CPU utilization always has a current value, memory usage is a present-moment reading. Git activity is different. Commits are discrete events at irregular intervals. “Activity” requires a definition the reference does not provide: commits from the last N minutes, or the last N commits? All branches or just the current one? What does the display show when the repository has seen no commits in the last hour, or when the working directory is not a repository at all?
These questions do not resolve from the htop reference because the underlying data models differ. A CPU utilization bar always has something to render; a git activity list may not. The gaps will surface as revision cycles: the developer runs the tool, sees that activity was computed or scoped differently than expected, and provides a correction.
This is the predictable boundary of reference-class specification: it transfers shape, interaction model, and visual conventions effectively, but it cannot transfer domain semantics where the reference and the target diverge. A specification combining a reference class with explicit statements for the domain-specific decisions handles this cleanly. “Like htop but for git, showing commits from the last 24 hours across all branches, refreshed every five seconds” extends the reference just far enough to resolve the semantic questions without requiring the developer to specify every visual detail from scratch.
The Technical Fit
For Go TUI development, the Charm toolkit is the natural match for an htop-style tool. bubbletea implements the Elm architecture, where the application divides into a model, an update function, and a view function. This structure maps onto the htop design pattern cleanly: a tick message drives the polling loop, update handles the data refresh, and view renders the current state to the terminal. The framework makes it structurally difficult to produce incoherent implementations across many agentic revision cycles because the seams between concerns are explicit.
For the git data layer, there is a choice worth noting. Shelling out to git log with a format string is the straightforward path:
cmd := exec.Command("git", "-C", repoPath, "log",
"--format=%H%x00%an%x00%at%x00%s",
"--max-count=100",
)
out, err := cmd.Output()Each refresh cycle forks a subprocess, introducing roughly 5-20ms of overhead. At a one-second refresh interval, this is generally fine. go-git, a pure-Go git implementation that accesses repository objects in-process without spawning the git binary, eliminates that overhead entirely. The Rust-based gitui made the analogous choice by using libgit2 via git2-rs rather than subprocess invocation, citing latency on large repositories as the motivation. lazygit’s reliance on subprocess calls has been a documented source of sluggishness on repositories with large histories.
For GitTop at a one-second refresh interval over a single repository, the subprocess approach is adequate. The htop design contract sets the genre expectation at roughly one-second updates, which gives subprocess polling comfortable headroom. Extending the tool toward multi-repository aggregation or sub-second refresh would make the go-git trade-off worth revisiting.
What This Means for Agentic Specification Practice
GitTop is an early data point in a question that will matter more as agentic coding becomes common: how do developers write specifications that produce useful output without requiring extensive correction cycles?
Reference-class specification is one approach, and it is productive when the reference tool has strong conceptual integrity and wide representation in training data. htop qualifies on both counts. The genre it established is coherent, consistent, and documented across enough tooling discussions, tutorials, and code repositories that an agent’s priors about it are reliable.
The broader principle is treating specification quality as a first-class concern rather than a preamble to directing the agent. In a fully agentic workflow, the specification is where most of the design work happens. Getting it right, through reference classes, explicit domain semantics, or a combination of both, is what determines whether the agent produces something usable on the first few passes or arrives at the intended result only after extensive correction. The GitTop experiment worked because the specification was dense. That is reproducible, and it is the clearest lesson the project offers.