fr3ktmux

AI Dev Workflow TMUX Visualization System - Real-time monitoring dashboards with optional GUI app integration

🎯 What is fr3ktmux?

A powerful TMUX-based dashboard system that visualizes your AI development workflow in real-time across multiple panes with beautiful ASCII art enhancements.

Features:

• 📊 6-Pane Monitoring Layout - Current task, system status, logs, progress, file changes, agent coordination
• 🎨 ASCII Art Visualizations - Progress bars, charts, banners, and gauges
• 🖥️ GUI App Integration - Display Chrome, VLC, Firefox in terminal via term.everything
• 🔄 Real-time Updates - Live process monitoring and resource tracking
• 🎭 4 Beautiful Themes - Cyberpunk, Matrix, Minimal, Retro
• 🛡️ TAC-Compliant - Validation layers, self-correction, feedback loops

🚀 Quick Start

# Install files
npx fr3ktmux install

# Run interactive setup wizard
npx fr3ktmux setup

# Start the dashboard
npx fr3ktmux start

# Start hybrid mode (dashboards + GUI apps)
npx fr3ktmux start hybrid

📦 Installation

Prerequisites

• TMUX ≥ 2.8 (Terminal multiplexer)
• Bash ≥ 4.0
• Node.js ≥ 14.0
• term.everything (optional, for GUI apps)

Install TMUX

# Ubuntu/Debian
sudo apt-get install tmux

# macOS
brew install tmux

# Verify installation
tmux -V

Validate System

npx fr3ktmux validate

🎮 Usage

Commands

npx fr3ktmux install           # Install files to ~/.fr3ktmux
npx fr3ktmux setup             # Interactive setup wizard
npx fr3ktmux start             # Start 6-pane dashboard
npx fr3ktmux start hybrid      # Start with GUI apps
npx fr3ktmux start split       # Dashboard + Apps in separate windows
npx fr3ktmux stop              # Stop session
npx fr3ktmux attach            # Re-attach to session
npx fr3ktmux status            # Show session status
npx fr3ktmux validate          # System validation
npx fr3ktmux help              # Show help

Pane Layout

╔═══════════════════╦═══════════════════╗
║  Current Task     ║  System Status    ║
║  🎯 What AI is    ║  💻 CPU/Memory    ║
║  working on now   ║  📊 Resources     ║
╠═══════════════════╬═══════════════════╣
║  Live Logs        ║  Task Progress    ║
║  📜 Tailing most  ║  📈 All tasks     ║
║  recent log       ║  with progress    ║
╠═══════════════════╬═══════════════════╣
║  File Changes     ║  Agent Coord      ║
║  📂 Git status &  ║  🤖 Active agents ║
║  modifications    ║  & coordination   ║
╚═══════════════════╩═══════════════════╝

Modes

Dashboard Mode (default)

npx fr3ktmux start
# 6-pane AI monitoring layout

Hybrid Mode

npx fr3ktmux start hybrid
# 9-pane layout: 6 monitoring + 3 GUI apps

Split Mode

npx fr3ktmux start split
# 2 windows: Dashboard | Apps
# Switch with: Ctrl+b 0/1

⚙️ Configuration

Setup Wizard

npx fr3ktmux setup

The interactive wizard will:

1. ✅ Validate TMUX installation
2. 🔍 Test pane splitting
3. 🎨 Choose theme (Cyberpunk/Matrix/Minimal/Retro)
4. ⏱️ Set refresh rates
5. 🎯 Configure paths
6. 💾 Save preferences to ~/.fr3ktmux/user-config.sh

Themes

Cyberpunk (default) - Magenta/Cyan/Yellow neon Matrix - Green on black, falling code aesthetic Minimal - Clean white/gray, simple and fast Retro - Amber/green CRT terminal vibes

Custom Configuration

Edit ~/.fr3ktmux/.tmux-ai/user-config.sh:

export THEME="matrix"
export REFRESH_CURRENT_TASK=2
export REFRESH_SYSTEM_STATUS=3
export CPU_ALERT_THRESHOLD=80

🖼️ GUI Apps Integration

Requires term.everything (converts GUI apps to ASCII in terminal)

# Install term.everything
# Download from: https://github.com/GerbenJavado/term.everything

# Start hybrid mode
npx fr3ktmux start hybrid

# Available apps:
# chrome, firefox, vlc, spotify, vscode, gimp,
# obs, discord, telegram, slack, zoom

🎹 Keyboard Shortcuts

| Key | Action | |-----|--------| | Ctrl+b % | Split pane vertically | | Ctrl+b " | Split pane horizontally | | Ctrl+b → | Navigate to pane on right | | Ctrl+b ← | Navigate to pane on left | | Ctrl+b ↑ | Navigate to pane above | | Ctrl+b ↓ | Navigate to pane below | | Ctrl+b z | Zoom/unzoom current pane | | Ctrl+b d | Detach from session | | Ctrl+b [ | Enter scroll mode (q to exit) |

🛠️ Programmatic API

const fr3ktmux = require('fr3ktmux');

// Validate system
const deps = fr3ktmux.validateDependencies();
const install = fr3ktmux.validateInstallation();

// Start dashboard
await fr3ktmux.start('dashboard');

// Start hybrid mode
await fr3ktmux.start('hybrid');

// Stop session
await fr3ktmux.stop();

// Check status
await fr3ktmux.status();

🐛 Troubleshooting

Session already exists

npx fr3ktmux stop
npx fr3ktmux start

Panes not displaying correctly

# Check terminal size
echo $COLUMNS x $LINES  # Should be at least 120x30

# Reset layout
tmux select-layout -t AI-DEV:0 tiled

Scripts not executable

chmod +x ~/.fr3ktmux/*.sh
chmod +x ~/.fr3ktmux/.tmux-ai/*.sh

Validation fails

npx fr3ktmux validate
# Follow the actionable error messages

📚 Advanced Usage

Multiple Sessions

# Create named session
tmux new-session -s my-project
# Attach to specific session
tmux attach-session -t my-project

Custom Layouts

Edit ~/.fr3ktmux/ai-tmux-manager.sh to customize pane sizes and positions.

Integration with MCP Tools

The system auto-detects tasks from hey-fr3k MCP server:

// Automatically shows tasks from:
mcp__hey-fr3k__get_incomplete_tasks()
mcp__hey-fr3k__get_tasks_ready_for_validation()

🏗️ Architecture

Built with TAC (Tactical Agentic Coding) principles:

• Validation Layer 1: Dependency checks (TMUX, bash, node)
• Validation Layer 2: Installation verification
• Self-Correction: Actionable error messages with fixes
• Feedback Loops: Real-time monitoring with auto-refresh

📄 License

MIT © fr3k

🔗 Links

• GitHub Repository
• Issue Tracker
• term.everything

🙏 Credits

Created by fr3k for AI-driven development workflows.

Made with 💜 for the AI dev community