Capsule

Capsule is a terminal user interface application built with Go and the BubbleTea framework, providing an intuitive file picker with keyboard navigation, dynamic theming, and a clean, responsive interface for terminal-based file selection.

Architecture

Capsule is built on the BubbleTea framework, which implements the Elm architecture in Go. This model-view-update pattern separates state, rendering, and logic into distinct concerns, making the application predictable and easy to maintain. The framework handles keyboard input and file system events through its event-driven system, while modular UI elements are composed from BubbleTea’s component ecosystem.

The core application state is managed through a single Model struct that tracks the current page, file picker state, selected files, and system operations. This centralized state management makes the application behavior deterministic and simplifies debugging.

type Model struct {
    CurrentPage    string
    PageTitles     []string
    InputsDisabled bool
    MiscMsgData    map[string]string
    Title          string
    err            error
    quitting       bool
    filepicker     filepicker.Model
    selectedFile   string
    operations     int
}

Key Features

File Navigation

The file picker supports intuitive keyboard navigation using either WASD or arrow keys, with visual indicators for directory traversal and file selection. The interface automatically abbreviates long directory names to maintain readability while preserving context. Navigation is responsive and provides immediate visual feedback for all interactions.

Dynamic Theming

A sophisticated theming system enables random theme switching on demand while maintaining a history of previous themes for easy navigation. The application uses custom color palettes with consistent styling across all components. Themes are applied through the BubbleTint library, which manages color schemes and ensures visual harmony throughout the interface.

func randomTint() {
    sliceOfTints = append(sliceOfTints, tint.GetCurrentTint())
    newTint := tint.DefaultRegistry.Tints()[rand.Intn(len(tint.DefaultRegistry.Tints()))]
    tint.SetTint(newTint)
    setStyles()
}

State Management

The application maintains its state through a combination of page-based navigation, file selection tracking, operation counting, and graceful shutdown handling. The Update function processes messages and transitions between states cleanly, ensuring the user experience remains smooth even during theme changes or file operations.

Technical Implementation

Styling System

Terminal styling is handled through Lipgloss, which provides advanced styling capabilities for terminal applications. The styling system defines multiple visual styles that adapt to the current theme, supporting both foreground and background colors with proper contrast ratios.

func setStyles() {
    mainStyle = lipgloss.NewStyle().Foreground(tint.Fg()).Bold(true)
    mainBgStyle = lipgloss.NewStyle().Foreground(tint.Fg()).Background(tint.Bg()).Bold(true)
    poyoStyle = lipgloss.NewStyle().Foreground(tint.Fg()).Bold(true)
    offStyle = lipgloss.NewStyle().Foreground(tint.Bg()).Bold(true)
    offBgStyle = lipgloss.NewStyle().Foreground(tint.Bg()).Background(tint.Fg()).Bold(true)
}

Project Structure

The codebase is organized into focused files: the main application logic in capsule.go, file picker styling in filepicker.go, utility functions in helpers.go, and UI rendering in views.go. This separation of concerns makes the codebase maintainable and allows for easy extension of functionality.

Cross-Platform Considerations

The application handles terminal compatibility challenges through responsive layout adaptation and minimum line count enforcement. Safe fallbacks are implemented for unsupported terminal features, ensuring the application works reliably across different operating systems and terminal emulators.

Usage

Install and run Capsule with standard Go commands:

git clone https://github.com/manveerbhullar/capsule.git
cd capsule
go build .
./capsule

The application supports comprehensive keyboard controls: W/S or arrow keys for navigation, D or right arrow to enter directories, A or left arrow to go back, E or enter to select files, number keys for theme switching, tab for page switching, and Q/Esc/Ctrl+C to quit.

---

View source: GitHub Repository