Skip to content

feat: Add tmux integration with multi-backend support#1

Open
Braddon wants to merge 1 commit intomainfrom
feat/tmux-integration
Open

feat: Add tmux integration with multi-backend support#1
Braddon wants to merge 1 commit intomainfrom
feat/tmux-integration

Conversation

@Braddon
Copy link
Owner

@Braddon Braddon commented Nov 6, 2025

Summary

This PR implements comprehensive tmux and GNU Screen support through a function-based abstraction layer, allowing hip-screen to seamlessly work with both terminal multiplexers.

Changes

Core Implementation

  • Backend detection: Auto-detects available multiplexer with tmux preference
  • 9 abstraction functions: Encapsulate all backend-specific operations
  • Environment variables: $HS_BACKEND to override, $HS_DEBUG for diagnostics
  • Session name validation: Prevents invalid tmux names with helpful error messages

Backend-Specific Optimizations

  • tmux: Uses native format variables (#{session_name}, #{session_attached}, #{session_activity})
  • screen: Uses socket file stats and ps parsing (maintains compatibility)

UI Updates

  • Header now shows active backend: hip-screen (tmux) or hip-screen (screen)
  • Session name validation prevents tmux errors upfront
  • Connection counts and last activity work with both backends

Documentation

  • Updated CLAUDE.md with complete backend architecture details
  • Rewrote README.md with backend selection guide, requirements, and troubleshooting
  • Added testing procedures for both backends

Breaking Changes

  • Header format changed from "There are N screen(s)" to "hip-screen (BACKEND) - N session(s)"
  • When using tmux, session names cannot contain periods (.), colons (:), or spaces (validation added)

Testing

Automated

  • ✅ Bash syntax check passes
  • ✅ Both backends detected correctly
  • ✅ Environment variable overrides work

Manual

  • ✅ tmux backend lists sessions correctly
  • ✅ screen backend lists sessions (including ones with spaces)
  • ✅ Current session highlighting works in both backends
  • ✅ Connection counts accurate
  • ✅ Last activity times display correctly
  • ✅ Backend indicator shows in header

Backward Compatibility

  • Existing screen users experience no changes (unless tmux is installed, then need export HS_BACKEND=screen)
  • All existing screen functionality preserved
  • Session names with spaces still work in screen backend

Migration Guide

For screen users who want to keep using screen:

export HS_BACKEND=screen

For users wanting to switch to tmux:

  • Install tmux: sudo apt install tmux (or brew/yum)
  • Run hs - will auto-detect tmux
  • Use hyphens/underscores in session names instead of spaces/periods/colons

Implements comprehensive tmux and GNU Screen support through a
function-based abstraction layer, allowing seamless switching between
terminal multiplexers.

Features:
- Auto-detection with tmux preference (override via $HS_BACKEND)
- 9 backend abstraction functions for all multiplexer operations
- Session name validation (tmux restricts periods, colons, spaces)
- Debug mode support via $HS_DEBUG environment variable
- Backend indicator in UI header

Backend-specific optimizations:
- tmux: Uses format variables for metadata (faster)
- screen: Uses socket file stats and ps parsing (compatible)

Breaking changes:
- Header changed from "There are N screen(s)" to "hip-screen (BACKEND) - N session(s)"
- tmux users cannot create sessions with periods, colons, or spaces

Documentation:
- Updated CLAUDE.md with backend architecture details
- Rewrote README.md with backend selection guide
- Added troubleshooting section for common issues
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant