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

[github-actions[bot]]

🐹 Go Fan Report: charmbracelet/huh (v0.8.0)

Module Overview

charmbracelet/huh is Charm's powerful library for building interactive terminal forms and prompts. It provides an elegant API for creating user-friendly CLI experiences with support for various field types (Input, Text, Select, MultiSelect, Confirm, FilePicker) and first-class accessibility mode for screen readers.

The repository was updated TODAY (2025-12-15) and is extremely well-maintained by the Charmbracelet team with 6,325 stars on GitHub.

Current Usage in gh-aw

Location: pkg/cli/interactive.go (540 lines)

Import Count: 1 file

Key APIs Used:

• huh.NewForm() + huh.NewGroup() for structured forms
• huh.NewInput() with validation and autocomplete
• huh.NewSelect[T]() and huh.NewMultiSelect[T]() for choices
• huh.NewText() for multi-line descriptions
• .WithAccessible() for screen reader support

Purpose: Interactive workflow creation wizard that guides users through:

1. Workflow naming (with autocomplete suggestions)
2. Trigger selection (issues, PRs, schedule, etc.)
3. AI engine selection (copilot, claude, codex, custom)
4. Tools configuration (github, bash, web-fetch, etc.)
5. Safe outputs (create-issue, add-comment, etc.)
6. Network access permissions
7. Workflow intent description

Research Findings

Version Status

• ✅ Current Version: v0.8.0 (October 14, 2025)
• ✅ Latest Version: v0.8.0
• ✅ Version Hygiene: EXCELLENT - Already on latest!

Recent Updates

v0.8.0 (October 14, 2025) - LATEST

• NEW: Field.RunAccessible is now public → enables custom field types! 🎉
• FIXED: Select visibility issues with filtering
• FIXED: Default value handling in Select/MultiSelect
• FIXED: Terminal.app rendering issues
• FIXED: Scrolling behavior improvements

v0.7.0 (April 16, 2025)

• Accessible mode improvements - better screen reader support
• NEW: GetFocusedField() - retrieve currently focused field
• NEW: Hovered() - check which option cursor is on
• NEW: GetFiltering() - detect if user is filtering
• Spinner improvements - better context handling, ActionWithError
• FilePicker polish - cursor customization, UI improvements
• Multi-line options - proper wrapping in Select/MultiSelect

v0.5.0 (July 9, 2024) - Dynamic Forms 🪄

• Form layouts - Column and Grid layouts for better space utilization
• Dynamic forms - TitleFunc, OptionsFunc, DescriptionFunc for reactive UIs
• WithTimeout - set form timeouts for CI safety
• WithInput - custom input sources

v0.4.2 (May 25, 2024) - FilePicker 📁

• NEW: FilePicker field for file/directory selection
• NEW: Predefined validation functions
• NEW: EchoMode for password inputs

v0.3.0 (January 25, 2024)

• Scrollable forms - auto-resize to fit terminal
• Autocomplete - suggestions for Input fields (gh-aw uses this!)
• 7x smaller binaries - improved compilation footprint

Best Practices from Repository

1. Accessibility First: Always provide accessible mode via WithAccessible() ✅ gh-aw does this!
2. Validation: Use inline validation with clear error messages ✅ gh-aw does this!
3. Autocomplete: Leverage Suggestions() for common inputs ✅ gh-aw does this!
4. Height Constraints: Use .Height() for long option lists ✅ gh-aw does this!
5. Dynamic Forms: Use TitleFunc, OptionsFunc for reactive fields ⚠️ Opportunity!
6. Type Safety: Use generic types for Select/MultiSelect options ✅ gh-aw does this!
7. Grouping: Organize related fields into logical groups ✅ gh-aw does this!

Improvement Opportunities

🏃 Quick Wins (Do These First!)

1. Add Confirm Field for File Overwrite ⭐⭐⭐

   • Current: Uses --force flag to overwrite existing workflows
   • Better: Use huh.NewConfirm() to prompt "Workflow exists. Overwrite? (y/n)"
   • Location: interactive.go:316 - replace stat check with Confirm field
   • Why: More intuitive than CLI flag, catches accidental overwrites
   • Effort: Very Low (5-10 minutes)
   • Impact: Prevents mistakes, better UX

2. Extract Validation Functions ⭐⭐

   • Current: Validation logic is inline in field definitions
   • Better: Extract to reusable, testable functions
   • Example:

     var validateWorkflowName = func(s string) error {
         if s == "" { return errors.New("workflow name cannot be empty") }
         if !isValidWorkflowName(s) { return errors.New("invalid characters") }
         return nil
     }

   • Why: Enables unit testing, improves maintainability
   • Effort: Very Low (15 minutes)
   • Impact: Better code quality

3. Add Form Timeout ⭐

   • Current: No timeout set on forms
   • Better: Add .WithTimeout(30 * time.Second) to all forms
   • Why: Extra safety for CI environments (already detecting CI)
   • Effort: Very Low (2 minutes)
   • Impact: Belt-and-suspenders protection

4. Extract Option Definitions to Constants ⭐

   • Current: Options defined inline in each function
   • Better: Package-level constants for reusability
   • Example: var TriggerOptions = []huh.Option[string]{...}
   • Why: Easier to maintain, consistent across codebase
   • Effort: Very Low (10 minutes)
   • Impact: Better maintainability

✨ Feature Opportunities (Nice UX Improvements)

1. Implement Dynamic Forms ⭐⭐⭐ (v0.5.0 feature)

   • What: Use TitleFunc and OptionsFunc for conditional options
   • Why: Current flow is linear; some options only make sense for certain selections
   • Examples:
     • Only show "ecosystem" network access if web-fetch/web-search tools selected
     • Show different tool options based on selected engine
     • Dynamically adjust safe outputs based on trigger type
   • Effort: Medium (2-3 hours)
   • Impact: Cleaner UX, reduces cognitive load

2. Add FilePicker for Template Selection ⭐⭐ (v0.4.2 feature)

   • What: Use huh.NewFilePicker() for selecting workflow templates
   • Why: Currently hardcoded generation; could allow template-based creation
   • Example: Let users pick from example templates in .github/workflows/templates/
   • Effort: Low (1 hour)
   • Impact: Better UX for advanced users, faster workflow creation

3. Integrate huh/spinner for Compilation ⭐⭐

   • What: Use huh/spinner package for workflow compilation progress
   • Why: Current "Compiling..." message is static
   • Example: Show animated spinner during compileWorkflow()
   • Effort: Low (30 minutes)
   • Impact: Better feedback during long operations
   • Note: Complements existing briandowns/spinner usage!

4. Add Context-Aware Help ⭐ (v0.7.0 feature)

   • What: Use GetFocusedField() to show dynamic help based on current field
   • Why: Current descriptions are static; could provide more guidance
   • Example: Show real-time validation feedback or examples as user types
   • Effort: Medium (2 hours)
   • Impact: Better UX, reduces errors

5. Support External Editor for Intent ⭐

   • What: Enable external editor support for Text field (intent description)
   • Why: Long descriptions might be easier to write in $EDITOR
   • Status: May already work! Test with .WithEditor() or document if disabled
   • Effort: Very Low if already supported
   • Impact: Better UX for complex descriptions

📐 Best Practice Alignment (Polish & Professional Touches)

1. Apply Custom Theme ⭐⭐

   • What: Use custom theme to match GitHub/gh-aw branding
   • Why: Currently using default theme; could match visual style
   • Options: Dracula, Catppuccin, Base16, or custom theme
   • Effort: Low (1 hour)
   • Impact: Professional polish

2. Explore Custom Field Types ⭐ (v0.8.0 feature)

   • What: Create reusable custom field types using new Field.RunAccessible API
   • Examples:
     • CronExpressionField with validation and common suggestions
     • GitHubRefField with branch/tag autocomplete
   • Effort: Medium (3-4 hours)
   • Impact: Powerful abstraction for domain-specific inputs

3. Add Form Layouts ⭐ (v0.5.0 feature)

   • What: Use Column/Grid layouts for better space utilization
   • Why: Single-column layout works but could be more efficient
   • Example: Show engine and network side-by-side on wide terminals
   • Effort: Medium (2 hours)
   • Impact: Better use of terminal real estate

4. Add Progress Indication ⭐

   • What: Show "Step X of Y" in form group titles
   • Why: Users want to know how far along they are
   • Example: "Step 2 of 6: Select AI Engine"
   • Effort: Very Low (5 minutes)
   • Impact: Better UX, sets expectations

🔧 General Code Quality Improvements

1. Documentation: Add inline comments explaining field choices and defaults
2. Testing: Add unit tests for validation functions (currently not testable)
3. Error Context: Use GetFocusedField() to provide better error context
4. Keyboard Shortcuts: Document available shortcuts in field descriptions
5. CI Safety: Consider adding WithInput to provide mock input in tests

Code Quality Assessment

Overall Rating: ⭐⭐⭐⭐ (4/5 stars)

Strengths:

• ✅ Excellent accessibility support with smart environment detection
• ✅ Clean, well-organized code structure
• ✅ Proper use of generics for type safety
• ✅ Good validation patterns with helpful error messages
• ✅ Helpful autocomplete suggestions for workflow names
• ✅ Already on latest version (v0.8.0)
• ✅ Leveraging most v0.3.0 features (scrolling, autocomplete, height constraints)

Areas for Improvement:

• ⚠️ Could leverage v0.5.0+ dynamic forms for conditional UI
• ⚠️ Could leverage v0.7.0+ focused field detection for better help
• ⚠️ Missing Confirm field for file overwrite scenarios
• ⚠️ Validation functions should be extracted for testability
• ⚠️ Could benefit from theme customization for branding

Recommendations

Priority 1: Do Now ⭐⭐⭐

1. Add Confirm field for overwrite - Better than --force flag, prevents mistakes
2. Extract validation functions - Enable testing and reuse
3. Add form timeout - Extra CI safety (30 seconds)

Priority 2: Do Soon ⭐⭐

1. Implement dynamic forms - Hide irrelevant options, cleaner UX
2. Add FilePicker - Template-based workflow creation
3. Integrate spinner - Better compilation feedback
4. Apply custom theme - Professional polish

Priority 3: Nice to Have ⭐

1. Custom field types - Leverage new v0.8.0 API for domain-specific fields
2. Form layouts - Better space utilization on wide terminals
3. Focused field help - Context-aware guidance
4. Progress indication - "Step X of Y" in titles

Specific Code Locations

File: pkg/cli/interactive.go

• Line 316: Replace os.Stat() check with huh.NewConfirm() for overwrite
• Line 131-139: Extract validation to reusable function
• Line 141: Add .WithTimeout(30 * time.Second)
• Line 148-157: Consider dynamic options based on previous selections
• Line 520: Add spinner integration in compileWorkflow()

Security & Compatibility

• ✅ No known security vulnerabilities
• ✅ Actively maintained (updated TODAY!)
• ✅ Stable API following semver
• ✅ Cross-platform (Windows, macOS, Linux)
• ✅ Screen reader compatible

In Production

Huh is widely used in the Go ecosystem:

• glyphs: Unicode symbol picker
• meteor: Conventional commit message tool
• freeze: Code image generator
• savvy: Runbook manager in CLI

All showcase focused, single-purpose interactive CLIs - perfect inspiration for gh-aw!

Next Steps

1. ✅ Review complete - Module summary saved to specs/mods/huh.md
2. 📋 Consider implementing Priority 1 improvements (quick wins)
3. 🎯 Explore dynamic forms for next major UX improvement
4. 📅 Next review: 2025-04-15 (or when v0.9.0 releases)

---

Module Summary: specs/mods/huh.md
Repository: https://github.com/charmbracelet/huh
Documentation: https://pkg.go.dev/github.com/charmbracelet/huh
Last Updated: 2025-12-15 (TODAY!)
Next Review: 2025-04-15

AI generated by Go Fan

[github-actions[bot]]

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