🎯 A complete web-native tmux experience with intelligent command routing and multi-user optimization.

Evolved from Amazon Q Session Manager to a full-featured multi-window tmux web interface.

• Gum-style API - Zero configuration required, just pass data
• Three-level compatibility - Simple to advanced customization
• Universal data support - Strings, keywords, maps, functions
• Real-time filtering with instant character input
• Multiple navigation options: ↑↓ arrows, Ctrl+P/N (Emacs), Ctrl+K (Vim)
• Blinking cursor feedback with professional visual polish
• Zero key collisions - type any character including 'q' to filter
• Fuzzy matching with instant session filtering

• Clickable tabs instead of dropdown menus
• Visual activity indicators with colored dots
• Instant window switching with perfect content sync
• Browser-like UX optimized for web users

• Bandwidth optimized for multi-user scenarios (<10 users)
• Window-specific streaming - only relevant updates sent
• Targeted broadcasting - users receive only their window's data
• Dynamic subscription management based on user selections

• Q commands (what, how, explain, ?) → Main session with Q&A
• Shell commands (ls, cd, echo) → Currently viewed window
• Intelligent detection based on command patterns
• Preserves Q&A functionality while enabling multi-window workflow

• Graceful browser cleanup - no JSON parsing errors
• Connection resilience - handles window close/refresh smoothly
• Dead connection cleanup - automatic resource management
• Error-resistant WebSocket communication

QQ features a professional-grade Terminal User Interface built from scratch with gum-style interactions and zero flicker rendering.

• Instant character input - Type any character for immediate filtering
• Fuzzy matching - Find sessions with partial character sequences
• Visual feedback - Live filter display with blinking cursor
• Zero key collisions - All printable characters available for filtering

• Arrow Keys - ↑↓ for universal navigation
• Emacs Style - Ctrl+P (previous) / Ctrl+N (next)
• Vim Style - Ctrl+K (up) for vim users
• Consistent behavior across all navigation methods

• Blinking cursor - Professional 500ms blink cycle
• Session status - 🟢 active / ⚪ inactive indicators
• Pane count display - Shows window/pane information
• Clean help text - Context-sensitive key bindings

• Reactive state management - Atom-based single source of truth
• Differential rendering - Only updates when content changes
• Flicker-free display - Professional-grade visual experience
• Terminal compatibility - Raw mode with proper cleanup

; Core TUI loop
State Atom → Watch → Content Compare → Render (if changed) → Terminal
     ↑                                                           ↓
Event Loop ← Input ← Terminal ←──────────────────────────────────┘

• Zero flicker - Differential rendering eliminates screen flash
• Low CPU usage - Only renders on actual state changes
• Responsive input - 50ms polling with non-blocking reads
• Smooth transitions - Content changes appear instantly

• Any character → Filter sessions instantly
• Backspace → Delete filter characters
• Escape → Clear entire filter

• ↑↓ Arrows → Navigate filtered results
• Ctrl+P → Previous (Emacs style)
• Ctrl+N → Next (Emacs style)
• Ctrl+K → Up (Vim style)

• Enter → Select and attach to session
• Ctrl+C → Quit TUI (no key collisions)

bb qq                    # Start interactive selector
# Type characters to filter
# Use arrows/Ctrl+P/N to navigate
# Press Enter to attach

bb qq
# Type "demo" → Shows only sessions with "demo"
# Type "q" → Shows sessions with "q" (no quit collision)
# Escape → Clear filter, show all sessions

bb qq
# Arrow users: ↑↓ to navigate
# Emacs users: Ctrl+P/Ctrl+N to navigate  
# Vim users: Ctrl+K to go up
# All styles work identically

• tmux-based testing - Real environment validation
• Visual confirmation - Direct output inspection
• Incremental development - One feature at a time
• Debug-driven approach - Minimal debug scripts when needed

• Character input detection - case vs cond for predicates
• Key collision resolution - Removed special 'q' handling
• Cursor blinking - Reactive state with background threads
• Terminal raw mode - Proper stty setup and cleanup

# Setup global 'bq' alias for universal access
bb setup

# Source your shell profile (or restart terminal)
source ~/.zshrc  # or ~/.bashrc

# Now use from any directory!
cd /my/project
bq qq my-work    # Creates qq-my-work in /my/project

# Interactive session selector with gum-style filtering
bb qq

# Features:
# - Type any character to filter sessions instantly
# - ↑↓/Ctrl+P/Ctrl+N/Ctrl+K for navigation  
# - Backspace to delete, Escape to clear filter
# - Enter to select session, Ctrl+C to quit

# Start tmux sessions
bb setup-tmux-sessions

# Start WebSocket server
bb start-terminal-server

# Open web interface
open http://localhost:9090/web/terminal.html

# Create Q session
bb create "Working on AWS Lambda optimization"

# Ask questions
bb ask "What causes Lambda cold starts?"

# List sessions
bb list

Browser Tabs ←→ WebSocket ←→ Server ←→ Tmux Windows
     ↓              ↓           ↓         ↓
  Tab UI    Window Subscription  Smart    Individual
  Activity   Management         Routing   Windows
  Tracking                      System

User Command → Command Detection → Route Decision
     ↓              ↓                    ↓
Q Command?     Pattern Match      Main Session (Q&A)
Shell Command? Content Analysis   Current Window

• Click tabs to switch between tmux windows instantly
• Orange dots indicate windows with new activity
• Green highlight shows currently active window
• + New button creates additional tmux windows

• Q Commands: what is Clojure?, explain functions, how to...
• Shell Commands: ls -la, cd /path, tail -f log.txt
• Automatic routing based on command content

• Multiple users can connect simultaneously
• Each user sees only their selected window's updates
• Bandwidth optimized for <10 concurrent users
• Independent window subscriptions per user

• Built professional-grade filtering with real-time character input
• Implemented multiple navigation key bindings (arrows, Emacs, Vim styles)
• Added blinking cursor and visual feedback systems
• Solved key collision issues for seamless user experience

• Replaced dropdown with clickable tabs
• Added visual activity indicators
• Implemented hover effects and smooth transitions
• Created web-native user experience

• Built user window subscription tracking
• Implemented window-specific tmux streaming
• Created targeted broadcasting for bandwidth optimization
• Added dynamic streaming management

• Developed intelligent command detection
• Implemented Q vs shell command routing
• Preserved Q&A functionality with multi-window support
• Created session-aware command processing

• Fixed JSON parsing errors during browser cleanup
• Implemented graceful connection termination
• Added comprehensive error logging
• Created resilient WebSocket communication

• Fluent operation with instant window switching
• Bandwidth optimized for multi-user scenarios
• Error-resistant connection handling
• Perfect content synchronization with tmux

• 🚀 Multiple Q Sessions: Independent Q conversations in separate tmux sessions
• 🏷️ Smart Naming: Auto-generated terse session names using Q itself
• 🔍 Fuzzy Search: Find sessions by partial name matching
• 📊 Context Tracking: Dynamic conversation summaries and theme extraction
• 🔄 Error Recovery: Auto-continue on Q errors for smooth operation
• 💾 Persistent Storage: Sessions saved in ~/.knock/qq/ with full history

bb create "context description"  # Create new Q session
bb ask "question"               # Ask current session
bb list                         # List all sessions with summaries
bb switch session-name          # Switch active session
bb attach session-name          # Get tmux attach command
bb dev-repl                     # Start development REPL

QQ consists of 5 core components:

• qq.core - Main API and CLI interface
• qq.session - Session management and persistence
• qq.tmux - Tmux integration and output capture
• qq.naming - Intelligent session naming service
• qq.context - Dynamic context tracking and summarization

• TUI Enhancement Log - Complete implementation journey and test methodology
• Default Window Design - Upcoming feature for immediate Q access
• Architecture - Detailed system design and component overview
• Development Log - Progress tracking and technical decisions

MVP Status: ✅ Core functionality validated and working

Working Features:

• Session creation and management
• Tmux integration with proper session handling
• CLI interface with clean output
• JSON persistence and session listing

In Progress:

• Default window for immediate access
• Context summarization improvements
• Enhanced naming service reliability

# Run tests
bb test

# Start development REPL
bb dev-repl

# Check available tasks
bb tasks

• Babashka - Clojure scripting environment
• tmux - Terminal multiplexer
• Amazon Q CLI - q chat command

This is an experimental project exploring multi-session AI conversation management. See Development Log for current priorities and technical decisions.

MIT License