← Back

tpm — Modernized Tmux Plugin Manager

2025 – Present Repository
Go Bubble Tea Tmux Git

Problem

The original Tmux Plugin Manager (by Bruno Sutic) is written entirely in Bash scripts, making it difficult to extend with advanced features like interactive UIs, concurrent operations, or visual progress tracking. Users had to rely on key bindings and opaque background processes without visibility into install/update progress. Adding new capabilities required wrestling with shell scripting limitations and portability issues.

Approach

Rewrote tpm from scratch in Go while maintaining 100% backward compatibility with the original. The Go binary handles all operations (install, update, clean, source) and introduces a new interactive TUI mode. A shell shim auto-detects the Go binary and falls back to the original Bash implementation if unavailable. This ensures existing users see zero breaking changes while new users benefit from the enhanced experience.

Technical Details

  • Backward Compatibility: Same config syntax (set -g @plugin), same key bindings (Prefix+I, Prefix+U, Prefix+Alt+U), same install directory structure
  • Interactive TUI: Built with Bubble Tea + Bubbles for visual plugin lists, outdated detection via git fetch, multi-select operations, and real-time progress bars/spinners
  • Popup Mode: tpm tui --popup launches the interface in a tmux popup window for quick access without leaving the terminal workflow
  • Multi-Platform: GoReleaser-based builds for Linux, macOS, FreeBSD (amd64, arm64)
  • Architecture: Clean separation with cmd/ (CLI), internal/manager/ (core logic), internal/tui/ (UI), internal/git/ (operations), internal/tmux/ (integration), internal/config/ (parsing)
  • Repository Support: GitHub, GitLab, Bitbucket, custom git repos with branch pinning (#branch syntax)
  • Timeouts: 5-minute timeout on install/update operations to prevent hangs

LLM-Augmented Development

LLMs were integral to the Bash-to-Go rewrite process:

  • Migration Analysis: Used Claude Code to analyze the original Bash scripts, map behaviors to Go equivalents, and identify implicit conventions that needed preserving
  • Backward Compatibility: LLM-assisted validation of config parsing edge cases to ensure 100% drop-in compatibility
  • TDD Acceleration: Scaffolded test suites with Claude Code, following red-green-refactor cycles for core plugin management logic

Results

  • Drop-in replacement for the original tpm — zero migration required
  • Interactive TUI with visual status for managing plugins at a glance
  • Background update checking surfaces outdated plugins without manual intervention
  • Progress indicators provide visibility into long-running git clone/pull operations