Specification by Analogy: Why 'Build Me Something Like htop' Works as a Project Brief

hjr265 recently built GitTop, a terminal TUI that shows git repository activity the way htop shows process activity, using a fully agentic coding workflow. The agent planned, wrote, and revised the code while the author evaluated outputs rather than driving implementation line by line.

Most discussion of this experiment focuses on familiar territory: where the agentic workflow earns its place, what Go and bubbletea contribute to agent-friendliness, and what the project reveals about fully agentic coding in general. Those observations are worth making. But there is a prior question that tends to go unexamined: why does “like htop but for git” work as a specification at all?

The Analogy Is Doing the Requirements Work

Specification is consistently identified as the hard part of agentic development. A developer directing an LLM agent is writing a requirements document in natural language and trusting that the agent resolves all ambiguities in ways that match their intent. For most projects, this is genuinely difficult. “Build me a tool that shows git activity” leaves dozens of questions unanswered: what activity, over what time period, sorted how, with what update frequency, handling what edge cases.

“Like htop” answers most of those questions without the developer articulating them.

htop is a terminal process viewer that has been maintained since 2004. It appears in system administration guides, is shipped by default on many Linux distributions, and is documented exhaustively in man pages, comparisons, screencasts, and tutorials across the internet. Its behavior is dense in the training data of any LLM trained on public text.

When you tell an agent to build something “like htop,” you invoke all of that prior knowledge. The agent has processed thousands of descriptions of how htop behaves, and this pre-answers a substantial number of design decisions:

• Update interval: htop refreshes roughly every second. A git tool built in its image will plausibly do the same, without the developer specifying a polling interval.
• Layout structure: htop uses a header area for summary statistics (CPU bars, memory, load averages) and a scrollable list below. The analogy suggests a header showing repository-level stats and a list of commits or contributors beneath it.
• Sort order and interactivity: htop defaults to CPU usage descending, allows column-based sorting, and uses function keys alongside vi-style navigation. A git equivalent will sort by something salient and provide keyboard controls in a familiar pattern.
• Color and visual density: htop uses color to distinguish states and surface important values against a dense layout. The analogy provides an aesthetic baseline.

None of these appear in the brief “show git activity like htop shows processes.” All of them are resolved by the analogy. This is specification compression, and it works specifically because the referenced system is dense enough in the agent’s training data that invoking its name is roughly equivalent to describing its behavior.

What the Compilation Loop Contributes

Beyond the specification, the Go compilation loop is worth examining as a feedback mechanism, because it functions quite differently from the test suites or behavioral verification that most agentic coding discussion assumes.

In a language with a strict compiler, a compilation error is a precise, machine-readable signal: line number, error type, often a suggested alternative. The agent gets binary feedback (compiled or did not) plus structured information about exactly what went wrong. For agentic code generation, this is close to an ideal feedback signal.

Go’s compiler produces consistently formatted, unambiguous error messages:

./main.go:42:15: undefined: tea.WithAltScreen
./model.go:87:3: cannot use commits (type []Commit) as type []interface {}

Each error is independently actionable. The agent does not need to infer what might be wrong; it is told specifically where and why. The correction loop stays short and productive in a way that the test suite for a web application, or the visual output of a TUI, is not.

The visual layer of a TUI is the exception to this. An agent cannot see what the rendered output looks like. It can read the source, reason about what the rendering code should produce, and run the binary, but it cannot close the visual feedback loop without a human to describe what is actually displayed. For GitTop, this means the agent can produce compilable, structurally correct code reliably, while the visual polish depends on human feedback about what the running tool shows.

This distinction matters as a general principle. go build and Go’s static type system verify a large fraction of what matters in a Go program. The residual correctness surface, runtime behavior, visual output, edge case handling, still requires human verification, but it is meaningfully smaller than in a dynamically typed language. The fully agentic workflow is strongest when the mechanical correctness surface is largest, and Go’s type system makes that surface unusually large.

Prior Art and the Design Space the Agent Navigates

Git visualization tools have a long history, and all of it is in the agent’s training data. tig, the text-mode interface for git, dates to 2006 and remains actively maintained, focused on history browsing and staging. lazygit provides a full-screen terminal interface for git operations, not just viewing, with a layout organized around the staging workflow. gitk ships with git itself and provides a graphical history browser. git-standup generates summary reports oriented around daily standups.

These tools represent implicit constraints on what a “git activity” view should look like and what it should not duplicate. An agent generating GitTop is navigating between these prior examples, drawing on htop’s interaction model, and producing something that occupies a specific niche: a real-time, process-monitor-style view of repository activity, as opposed to the interactive staging focus of lazygit or the history-browser focus of tig.

The density of this prior art in training data works in the agent’s favor. There are enough examples of how git data gets displayed, and enough examples of how htop-style tools work, that the agent is interpolating between well-understood reference points rather than reasoning in a vacuum. This is a different situation from asking an agent to build something genuinely novel, a new data visualization paradigm or an unusual concurrency model. In those cases, the agent cannot lean on training data density in the same way. The agentic workflow is at its strongest when the target occupies a region of the design space that is already well-covered by prior examples.

The Shell-Out Pattern and Training Data Density

GitTop reads git data by running subprocess commands and parsing their output, rather than using a library like go-git, which provides a pure-Go implementation of git’s internals without spawning processes.

The subprocess approach has specific advantages for agentic generation. The git log output format is documented, stable across versions, and extensively represented in code examples across the internet. An agent generating a parser for null-delimited git log output is drawing on dense training signal:

cmd := exec.Command("git", "-C", repoPath, "log",
    "--format=%H%x00%an%x00%ae%x00%ar%x00%s",
    "--max-count=100",
)
out, err := cmd.Output()

The format string uses null bytes as delimiters to avoid the obvious failure mode with commit subjects containing pipe characters. Using %ar for relative author date (“3 hours ago”) rather than a Unix timestamp gives display-ready output without an additional formatting step. An agent generating this code is not reasoning from first principles; it has seen close variants of this exact pattern in training data.

go-git, by contrast, has a smaller footprint in public documentation and a more complex API surface. For straightforward history reading, the subprocess approach is both more agent-friendly and simpler for a personal tool. The performance cost of spawning a git process on each refresh tick is negligible at terminal update frequencies.

This is a useful heuristic for agentic project design more broadly: where two approaches produce equivalent results, the one with denser representation in training data will be generated more reliably. For tools that shell out to stable, well-documented command-line interfaces, agents produce consistently better output than for tools that need to navigate complex or sparsely documented library APIs.

What Makes a Specification Agent-Friendly

GitTop points toward something worth making explicit. Fully agentic coding works best not simply when projects are small or bounded, but when the specification is dense in a particular sense. Density here has three components: the developer can invoke a shared mental model (htop, process monitors, existing git tools) rather than describing everything from first principles; the agent has substantial training signal in the technical domain (Go, bubbletea, git command output formats); and the feedback signal is high-quality where it matters most (compilation errors) and humanly verifiable where it is not (visual output).

GitTop satisfies all three conditions. The htop analogy provides specification density. The Go compilation loop provides technical feedback density. The developer is the primary user and can evaluate visual correctness by running the tool.

Personal developer tools are the natural domain for this combination. The developer knows the reference tools well enough to specify by analogy. The implementation is typically in a technically well-covered domain. The feedback loop is short because the developer is also the evaluator. This is why the category of “tools a developer has always meant to build” is such a natural fit for fully agentic workflows: low specification cost, high feedback density, and immediate evaluation by someone with direct domain knowledge.

The harder question is which of these conditions are preconditions imposed by project type, and which are design choices a developer can make deliberately. Specification by analogy does not scale to systems with no good reference point. Compilation-quality feedback requires either a strict type system or comprehensive test infrastructure. Human evaluation is cheap for personal tools and expensive at team scale. GitTop succeeds at all three without any deliberate optimization for agent-friendliness, which is the clearest evidence that the project type, not just the workflow, is doing significant explanatory work.