[go-fan] Go Module Review: charmbracelet/huh

[github-actions[bot]]

Module Overview

Huh (github.com/charmbracelet/huh v0.8.0) is a modern, terminal-based forms library that provides an elegant API for building interactive CLI wizards. Part of the Charm ecosystem, it offers various field types with built-in validation, accessibility support, and beautiful default themes.

Current Usage in gh-aw

The project uses Huh exclusively in the interactive workflow creation wizard (pkg/cli/interactive.go), which guides users through configuring agentic workflows via a series of prompts.

Implementation Stats

• Files: 1 file (497 lines of interactive workflow building logic)
• Import Count: Single import for the main package
• Key APIs Used:
  • NewForm(), NewGroup() - Form structure
  • NewInput() - Workflow name entry
  • NewSelect[string]() - Single choice (trigger, engine, network)
  • NewMultiSelect[string]() - Multiple choice (tools, safe outputs)
  • NewText() - Multi-line intent description
  • NewOption() - Option creation for selects

Current Workflow Prompts

The interactive builder collects:

1. Workflow name (if default)
2. Trigger type (8 options: dispatch, issues, PR, push, comment, schedules, command)
3. AI engine (4 options: copilot, claude, codex, custom)
4. Tools access (6 tool types via MultiSelect)
5. Safe outputs (10 output types via MultiSelect)
6. Network access (2 levels: defaults, ecosystem)
7. Workflow intent/description (multi-line text)

Research Findings

Recent Updates (v0.8.0 - October 2025)

• Custom Field Types: Field.RunAccessible is now public, enabling custom field implementations
• Bug Fixes: Improved select/multiselect default handling, fixed rendering issues, better scrolling
• Accessibility: Enhanced screen reader support in accessible mode

Key Features Available

• Dynamic Forms (v0.5.0): Forms that react to changes with TitleFunc/OptionsFunc
• Autocomplete (v0.3.0): Input suggestions with configurable keybindings
• Scrolling (v0.3.0): Scrollable forms and select fields for long lists
• Layouts (v0.5.0): Column and grid layouts for complex forms
• Validation: Built-in validation with custom error messages
• Themes: Five predefined themes (Charm, Dracula, Catppuccin, Base 16, Default)
• Accessibility: Automatic accessible mode for screen readers (TERM=dumb)
• Spinner: Loading state component for long operations
• FilePicker (v0.4.0): File selection component

Improvement Opportunities

🏃 Quick Wins

1. Add Input Validation

// Current (line 96)
huh.NewInput().
    Title("What should we call this workflow?").
    Value(&b.WorkflowName)

// Improved
huh.NewInput().
    Title("What should we call this workflow?").
    Value(&b.WorkflowName).
    Validate(func(s string) error {
        if s == "" {
            return errors.New("workflow name cannot be empty")
        }
        if !isValidWorkflowName(s) {
            return errors.New("workflow name must contain only alphanumeric characters and hyphens")
        }
        return nil
    })

2. Enable Accessibility Mode

// Add to form creation
form := huh.NewForm(...).
    WithAccessible(os.Getenv("TERM") == "dumb" || 
                   os.Getenv("NO_COLOR") != "")

3. Add Height Constraints for Long Lists

// For safe outputs (10 options)
huh.NewMultiSelect[string]().
    Title("What outputs should the AI be able to create?").
    Options(outputOptions...).
    Height(8).  // Make it scrollable
    Value(&selected)

✨ Feature Opportunities

1. Dynamic Tool Selection Based on Engine

Currently, all tools are shown regardless of engine choice. Use dynamic forms to show engine-appropriate tools:

huh.NewMultiSelect[string]().
    Title("Which tools should the AI have access to?").
    OptionsFunc(func() []huh.Option[string] {
        // Copilot might not need all tools that Claude does
        return getToolsForEngine(b.Engine)
    }, &b.Engine).  // React when engine changes
    Value(&selected)

2. Autocomplete for Workflow Names

Add common workflow pattern suggestions:

huh.NewInput().
    Title("What should we call this workflow?").
    Suggestions([]string{
        "issue-triage",
        "pr-review-helper",
        "code-quality-check",
        "security-scan",
        "daily-report",
        "release-notes",
    }).
    Value(&b.WorkflowName)

3. Spinner for Compilation Step

Replace the static message with an animated spinner:

import "github.com/charmbracelet/huh/spinner"

func (b *InteractiveWorkflowBuilder) compileWorkflow(verbose bool) error {
    var err error
    _ = spinner.New().
        Title("Compiling the generated workflow...").
        Action(func() {
            config := CompileConfig{...}
            _, err = CompileWorkflows(config)
        }).
        Run()
    return err
}

4. Multi-Field Groups for Better Flow

Combine related fields to reduce navigation:

// Instead of separate prompts, group related fields
huh.NewForm(
    huh.NewGroup(
        huh.NewSelect[string]().Title("Engine").Value(&b.Engine),
        huh.NewSelect[string]().Title("Trigger").Value(&b.Trigger),
    ).Title("Basic Configuration"),
    huh.NewGroup(
        huh.NewMultiSelect[string]().Title("Tools").Value(&b.Tools),
        huh.NewMultiSelect[string]().Title("Outputs").Value(&b.SafeOutputs),
    ).Title("Permissions"),
)

5. Use Column Layout for Compact Choices

For binary choices like network access:

form := huh.NewForm(...).
    WithLayout(huh.LayoutColumns(2))  // Side-by-side layout

📐 Best Practice Alignment

1. Consistent Default Values

Currently only NetworkAccess sets a default before the form. Apply defaults consistently:

// In CreateWorkflowInteractively
builder := &InteractiveWorkflowBuilder{
    WorkflowName:  workflowName,
    Trigger:       "workflow_dispatch",  // Default
    Engine:        "copilot",             // Default
    NetworkAccess: "defaults",            // Already done
    Tools:         []string{"github"},    // Sensible default
}

2. Extract Option Definitions

Option lists are defined inline. Extract for reusability and testing:

var (
    triggerOptions = []huh.Option[string]{
        huh.NewOption("Manual trigger (workflow_dispatch)", "workflow_dispatch"),
        huh.NewOption("Issue opened or reopened", "issues"),
        // ...
    }
    
    engineOptions = []huh.Option[string]{
        huh.NewOption("copilot - GitHub Copilot CLI", "copilot"),
        // ...
    }
)

3. Improve Error Context

Current error handling wraps errors but doesn't guide users:

// Current (line 55)
if err := builder.promptForTrigger(); err != nil {
    return fmt.Errorf("failed to get trigger selection: %w", err)
}

// Improved
if err := builder.promptForTrigger(); err != nil {
    if errors.Is(err, huh.ErrUserAborted) {
        return fmt.Errorf("workflow creation cancelled by user")
    }
    return fmt.Errorf("failed to get trigger selection: %w\nPlease try again or use --help for more options", err)
}

4. Add Theme Support

Consider adding custom theme or allowing user selection:

theme := huh.ThemeCharm()  // or detect from environment
if darkMode := os.Getenv("COLORFGBG"); darkMode != "" {
    theme = huh.ThemeDracula()
}
form := huh.NewForm(...).WithTheme(theme)

🔧 General Improvements

1. FilePicker for Workflow Templates

Allow users to start from existing workflow templates:

var useTemplate bool
var templatePath string

huh.NewConfirm().
    Title("Start from a template?").
    Value(&useTemplate)

if useTemplate {
    huh.NewFilePicker().
        Title("Select a workflow template:").
        AllowedTypes([]string{".md"}).
        CurrentDirectory(".github/workflows").
        Value(&templatePath)
}

2. Form State Persistence

Save progress if user quits mid-flow:

// Detect user abort and save state
if err := form.Run(); err != nil {
    if errors.Is(err, huh.ErrUserAborted) {
        saveState(builder)  // Save to ~/.gh-aw/workflow-state.json
        fmt.Println("Progress saved. Run 'gh aw new --resume' to continue.")
    }
    return err
}

3. Add WithInput/WithOutput for Testing

Improve test coverage with custom I/O:

// In tests
var buf bytes.Buffer
form := huh.NewForm(...).
    WithInput(strings.NewReader("test-workflow\n")).
    WithOutput(&buf)

4. Leverage GetFocusedField() for Real-Time Validation

Provide immediate feedback as users navigate:

// After each field
field := form.GetFocusedField()
if input, ok := field.(*huh.Input); ok {
    if err := validateInRealTime(input.Value()); err != nil {
        // Show warning
    }
}

5. Add Contextual Help

Show tips based on current field:

huh.NewSelect[string]().
    Title("Which AI engine should process this workflow?").
    Description("Copilot is recommended for most use cases. Claude offers deeper reasoning for complex tasks.").
    Options(engineOptions...).
    Value(&b.Engine)

Recommendations

Priority 1: Quick Wins (Immediate Impact)

1. Add input validation for workflow name
2. Enable accessibility mode detection
3. Add height constraints to long select lists
4. Extract option definitions to constants

Priority 2: Enhanced User Experience

1. Implement autocomplete for workflow names
2. Add spinner for compilation step
3. Group related fields together
4. Apply consistent default values

Priority 3: Advanced Features

1. Dynamic forms for context-aware options
2. FilePicker for template selection
3. Form state persistence for resume capability
4. Custom theme support

Priority 4: Code Quality

1. Improve error messages and user guidance
2. Add integration tests with custom I/O
3. Document usage patterns
4. Real-time validation feedback

Next Steps

1. Immediate: Add validation to the workflow name input (prevents invalid configurations)
2. Short-term: Enable accessibility mode and add scrolling to long lists (better UX)
3. Medium-term: Implement autocomplete and spinner (polish the experience)
4. Long-term: Consider dynamic forms and template system (advanced features)

Module Health: Excellent ✅

Huh is actively maintained, well-documented, and follows Go best practices. The project uses it appropriately for its interactive CLI needs. The suggested improvements focus on leveraging newer features (v0.3.0-v0.8.0) that weren't available when the code was originally written.

---

Generated by Go Fan 🐹
Module summary saved to: specs/mods/huh.md

AI generated by Go Fan

[pelikhan]

/plan

[github-actions[bot]]

🎉 Yo ho ho! Plan Command found the treasure and completed successfully! ⚓💰

[github-actions[bot]]

⚓ Avast! This discussion be marked as outdated by Go Fan.
🗺️ A newer treasure map awaits ye at Discussion #5271.
Fair winds, matey! 🏴‍☠️