Terminal Stylist: Console Output Analysis for gh-aw

[github-actions[bot]]

This report analyzes console output patterns across the gh-aw codebase, focusing on Lipgloss styling, Huh form implementations, and output consistency.

Workflow run: §23219177246

---

Executive Summary

The codebase has a strong foundational architecture for styled terminal output. The pkg/console and pkg/styles packages are well-designed and widely adopted. However, ~534 raw stderr writes remain outside the console formatting system, and the pkg/workflow package contains debug/warning messages that bypass console formatters. Interactive forms (Huh) are consistently accessible. Lipgloss adaptive colors and TTY detection are correctly implemented throughout the core infrastructure.

Metric	Value
Go source files (non-test)	583
Files using console.Format* / console.Render*	142
Total console.Format* calls	1,438
Raw fmt.Fprintf(os.Stderr, …) calls (non-console)	534
Huh forms using WithAccessible()	100% (11/11 forms)
Lipgloss adaptive color usage	✅ All colors use AdaptiveColor
TTY detection in applyStyle()	✅ Correct

---

Lipgloss Analysis

✅ Strengths

Adaptive color system (pkg/styles/theme.go) — All 10 semantic colors use lipgloss.AdaptiveColor with distinct light/dark variants. The palette is Dracula-inspired for dark mode and uses muted, high-contrast colors for light mode. This is exemplary:

ColorError = lipgloss.AdaptiveColor{
    Light: "#D73737",  // Darker red for light backgrounds
    Dark:  "#FF5555",  // Bright red for dark backgrounds (Dracula)
}

TTY-aware rendering (pkg/console/console.go) — The applyStyle() helper correctly gates all Lipgloss rendering:

func applyStyle(style lipgloss.Style, text string) string {
    if isTTY() {
        return style.Render(text)
    }
    return text
}

Rich table rendering — RenderTable() in console.go uses lipgloss/table with styled headers, zebra-striped rows, rounded borders, and a configurable total row.

Bubble Tea interactive list (pkg/console/list.go) — Full Bubble Tea model with a non-TTY text fallback, custom item delegate using Lipgloss styles for selected/normal/description states, and filter support.

Semantic border constants — RoundedBorder, NormalBorder, ThickBorder are defined centrally in pkg/styles/theme.go ensuring consistent use.

⚠️ Issues and Opportunities

Logger uses raw ANSI codes (pkg/logger/logger.go) — The logger uses hardcoded \033[38;5;Xm escape sequences instead of Lipgloss. While it has TTY detection, this diverges from the Lipgloss-based approach used everywhere else:

// Current — hardcoded ANSI
colorReset = "\033[0m"
colors = []string{"\033[38;5;33m", "\033[38;5;35m", ...}

// Preferred — use Lipgloss
lipgloss.NewStyle().Foreground(lipgloss.Color("33")).Render(text)

Manual list bullet points — Several files use raw • bullets in fmt.Fprintf calls instead of console.FormatListItem():

// Current (audit_report_render.go, preconditions.go, etc.)
fmt.Fprintf(os.Stderr, "  • %s (%s)", file.Path, formattedSize)

// Preferred
fmt.Fprintln(os.Stderr, console.FormatListItem(fmt.Sprintf("%s (%s)", file.Path, formattedSize)))

RenderTitleBox and RenderInfoSection check IsStderrTerminal but the list fallback uses raw formatting — Minor inconsistency: ShowInteractiveList correctly checks tty.IsStderrTerminal() for the list but then calls fmt.Fprintf(os.Stderr, ...) directly in the fallback without style helpers.

Top files with raw stderr writes (opportunities for improvement)

File	Raw writes	Has console.Format*
pkg/cli/audit_report_render.go	90	✅ Yes (mixed)
pkg/cli/mcp_inspect_mcp.go	41	✅ Yes (mixed)
pkg/cli/engine_secrets.go	32	✅ Yes (mixed)
pkg/cli/preconditions.go	27	✅ Yes (mixed)
pkg/cli/shell_completion.go	21	✅ Yes (mixed)
pkg/cli/add_interactive_workflow.go	19	✅ Yes (mixed)
pkg/cli/copilot_setup.go	19	✅ Yes (YAML code output — intentional)
pkg/cli/add_interactive_git.go	18	✅ Yes (mixed)
pkg/cli/add_interactive_orchestrator.go	15	✅ Yes (mixed)
pkg/cli/fix_command.go	14	✅ Yes (mixed)
pkg/workflow/claude_logs.go	8	❌ No
pkg/workflow/cache.go	2	❌ No
pkg/workflow/mcp_renderer.go	1	❌ No

Note: Many of the 90 raw writes in audit_report_render.go are empty fmt.Fprintln(os.Stderr) spacers — these are acceptable. The bullet-point writes are the primary improvement opportunity.

---

Huh Forms Analysis

✅ Strengths

100% accessibility compliance — All 11 huh.NewForm() calls across 11 files include .WithAccessible(console.IsAccessibleMode()). This is a standout achievement:

// Consistent pattern across all interactive forms
form := huh.NewForm(
    huh.NewGroup(/* fields */),
).WithAccessible(console.IsAccessibleMode())

Rich field types used — The codebase uses the full range of Huh field types appropriately:

• huh.NewInput() — workflow name, single-line text collection
• huh.NewText() — multi-line intent description
• huh.NewSelect[string]() — engine selection, trigger selection, network access
• huh.NewMultiSelect[string]() — tool selection, safe output channels
• huh.NewConfirm() — destructive action confirmation (pkg/console/confirm.go)
• huh.EchoModePassword — secrets input (pkg/console/input.go)

Well-organized form groups — interactive.go splits configuration into 4 logical groups (workflow identity → triggers/engine → tools/outputs → network/intent), providing good UX paging.

Centralized primitives — pkg/console/confirm.go and pkg/console/input.go provide reusable single-field form wrappers for common prompts.

⚠️ Issues and Opportunities

No custom Huh theme — Forms use the default Huh theme. The project has a rich pkg/styles theme that could be applied to Huh via huh.NewTheme() or by customizing field styles, creating a more cohesive visual identity.

Missing validation in some forms — add_interactive_workflow.go uses Validate() on the workflow name input, but other forms (e.g., the intent text in interactive.go) skip validation. The intent field accepts empty strings without warning.

add_interactive_secrets.go doesn't use Huh — While other interactive add-flows use huh forms, add_interactive_secrets.go doesn't import Huh at all (secrets are handled by engine_secrets.go). This is fine architecturally but worth noting for consistency.

---

Recommendations

High Priority

1. Apply FormatListItem() consistently for bullet points — Replace raw fmt.Fprintf(os.Stderr, " • %s\n", ...) calls with console.FormatListItem() in audit_report_render.go, preconditions.go, and mcp_inspect_mcp.go. This ensures bullets get the themed styles.ListItem styling and TTY detection.

2. Migrate logger colors to Lipgloss — Replace the 12 hardcoded \033[38;5;Xm ANSI sequences in pkg/logger/logger.go with Lipgloss-derived color strings. This consolidates color management and ensures adaptive light/dark support for debug output.

3. Add console formatting to pkg/workflow warnings — claude_logs.go, cache.go, and mcp_renderer.go write raw Warning: and error strings directly to stderr without console formatting. These should use console.FormatWarningMessage() / console.FormatErrorMessage() for visual consistency.

Medium Priority

4. Implement a custom Huh theme — Create pkg/styles/huh_theme.go that maps the existing pkg/styles colors into a huh.Theme. This would give forms the same Dracula-inspired palette as the rest of the CLI output.

5. Add FormatLocationMessage and FormatCountMessage to console.go — These functions exist in console_wasm.go as stubs but have no non-wasm implementation. If these are intended for future use, add the Lipgloss-styled implementations to console.go.

6. Add intent field validation — The huh.NewText() field for workflow intent in interactive.go should validate non-empty input, consistent with the workflow name field's Validate() call.

Low Priority

7. Reduce empty-line writes — There are 61 fmt.Fprintln(os.Stderr) calls for spacing. Consider a console.PrintSpacer() helper that in non-TTY mode omits extra blank lines (useful for cleaner CI output).

8. Standardize RenderInfoSection fallback — The non-TTY fallback in pkg/console/list.go's showTextList uses raw fmt.Fprintf without the applyStyle wrapper. Minor inconsistency with the TTY-detection pattern used elsewhere in the console package.

---

Good Pattern Examples

✅ Exemplary Lipgloss pattern (pkg/console/console.go)

// TTY-aware style application
func applyStyle(style lipgloss.Style, text string) string {
    if isTTY() {
        return style.Render(text)
    }
    return text
}

// Consistent format functions
func FormatSuccessMessage(message string) string {
    return applyStyle(styles.Success, "✓ ") + message
}
func FormatErrorMessage(message string) string {
    return applyStyle(styles.Error, "✗ ") + message
}

✅ Exemplary Huh form pattern (pkg/cli/interactive.go)

form := huh.NewForm(
    huh.NewGroup(
        huh.NewInput().
            Title("Workflow name").
            Value(&builder.WorkflowName).
            Validate(func(s string) error {
                if s == "" { return errors.New("workflow name cannot be empty") }
                return nil
            }),
    ),
    huh.NewGroup(
        huh.NewSelect[string]().Title("Engine").Options(engineOptions...).Value(&builder.Engine),
        huh.NewMultiSelect[string]().Title("Tools").Options(toolOptions...).Value(&builder.Tools),
    ),
).WithAccessible(console.IsAccessibleMode())

References:

• §23219177246

AI generated by Terminal Stylist · history

• expires on Mar 18, 2026, 10:30 PM UTC

[pelikhan]

/plan

[github-actions[bot]]

🚀 Plan Command has started processing this discussion comment

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #21658.