Feature Request: Support Custom tmux Layout Definitions

[JeremyDev87]

Feature Request: Support Custom tmux Layout Definitions

Summary

Add support for custom tmux layout configurations (beyond the default tiled layout) to allow users to define and reuse specific pane arrangements optimized for their workflows.

Motivation

The current taskMaestro implementation creates panes using tmux's tiled layout, which distributes panes evenly. However, many workflows benefit from asymmetric layouts, such as:

• Multiple small panes for parallel tasks + one large monitoring/log pane
• Specific grid arrangements (e.g., 2x5 grid + full-width bottom pane)
• Preserved layouts that users have manually fine-tuned

Proposed Solution

1. Layout Definition Format

Store custom layouts in .taskmaestro/layouts/ directory:

.taskmaestro/
├── layouts/
│   ├── 21-panes.layout    # Layout string for 21 panes
│   ├── 11-panes.layout    # Layout string for 11 panes
│   └── custom.layout      # User-defined layouts

Each .layout file contains a tmux layout string (obtained via tmux display-message -p "#{window_layout}").

2. Configuration Schema

Add layout configuration to taskMaestro settings:

{
  "layouts": {
    "11-panes": {
      "file": ".taskmaestro/layouts/11-panes.layout",
      "description": "2 rows x 5 columns + full-width bottom pane",
      "paneCount": 11
    },
    "21-panes": {
      "file": ".taskmaestro/layouts/21-panes.layout",
      "description": "4 rows x 5 columns + full-width bottom pane",
      "paneCount": 21
    }
  }
}

3. Usage API

Extend the taskMaestro CLI to support layout selection:

# Use predefined layout
taskmaestro --layout 11-panes --tasks "task1,task2,..."

# Use custom layout file
taskmaestro --layout-file .taskmaestro/layouts/custom.layout --tasks "..."

# Save current layout
taskmaestro save-layout --name my-layout

# List available layouts
taskmaestro list-layouts

Implementation Details

Example: 11-Pane Layout

Structure:

┌──────┬──────┬──────┬──────┬──────┐
│  1   │  2   │  3   │  4   │  5   │  Top row (36px height)
├──────┼──────┼──────┼──────┼──────┤
│  6   │  7   │  8   │  9   │  10  │  Middle row (36px height)
├──────────────────────────────────┤
│              11                  │  Bottom pane (16px height, full width)
└──────────────────────────────────┘

Layout String:

4cb3,375x90,0,0[375x36,0,0{75x36,0,0,55,75x36,76,0,61,75x36,152,0,60,75x36,228,0,59,71x36,304,0,58},375x36,0,37{75x36,0,37,57,75x36,76,37,65,75x36,152,37,64,75x36,228,37,63,71x36,304,37,62},375x16,0,74,56]

Creation Script:

#!/bin/bash
WINDOW_NAME="${1:-work-11}"
LAYOUT_FILE=".taskmaestro/layouts/11-panes.layout"

if [ ! -f "$LAYOUT_FILE" ]; then
  echo "❌ Layout file not found: $LAYOUT_FILE"
  exit 1
fi

LAYOUT=$(cat "$LAYOUT_FILE")

tmux new-window -n "$WINDOW_NAME"

# Create panes structure
tmux split-window -t "$WINDOW_NAME" -v -p 60
tmux split-window -t "$WINDOW_NAME.1" -v -p 67

# First row: 5 panes
for i in {1..4}; do
  tmux split-window -t "$WINDOW_NAME.1" -h
done

# Second row: 5 panes
for i in {1..4}; do
  tmux split-window -t "$WINDOW_NAME.6" -h
done

# Apply saved layout
tmux select-layout -t "$WINDOW_NAME" "$LAYOUT"

Example: 21-Pane Layout

Structure:

┌──┬──┬──┬──┬──┐
│1 │2 │3 │4 │5 │  Row 1 (16px)
├──┼──┼──┼──┼──┤
│6 │7 │8 │9 │10│  Row 2 (17px)
├──┼──┼──┼──┼──┤
│11│12│13│14│15│  Row 3 (17px)
├──┼──┼──┼──┼──┤
│16│17│18│19│20│  Row 4 (17px)
├─────────────┤
│     21      │  Bottom (19px, full width)
└─────────────┘

Layout String:

78dc,375x90,0,0[375x16,0,0{74x16,0,0,1,74x16,75,0,6,74x16,150,0,10,74x16,225,0,14,75x16,300,0,18},375x17,0,17{74x17,0,17,19,74x17,75,17,20,74x17,150,17,21,74x17,225,17,15,75x17,300,17,16},375x17,0,35{74x17,0,35,17,74x17,75,35,11,74x17,150,35,12,74x17,225,35,13,75x17,300,35,7},375x17,0,53{74x17,0,53,8,74x17,75,53,9,74x17,150,53,3,74x17,225,53,4,75x17,300,53,5},375x19,0,71,2]

Creation Script:

#!/bin/bash
WINDOW_NAME="${1:-parallel-work}"
LAYOUT_FILE=".taskmaestro/layouts/21-panes.layout"

if [ ! -f "$LAYOUT_FILE" ]; then
  echo "❌ Layout file not found: $LAYOUT_FILE"
  exit 1
fi

LAYOUT=$(sed -n '2p' "$LAYOUT_FILE")  # Second line if multi-line file

tmux new-window -n "$WINDOW_NAME"

# Create 20 additional panes (1 already exists)
for i in {1..20}; do
  tmux split-window -t "$WINDOW_NAME"
  tmux select-layout -t "$WINDOW_NAME" tiled  # Temporary even distribution
done

# Apply saved layout
tmux select-layout -t "$WINDOW_NAME" "$LAYOUT"

Benefits

1. Flexibility: Users can define layouts optimized for their specific workflows
2. Reproducibility: Layouts can be version-controlled and shared across teams
3. Efficiency: One large monitoring pane + multiple smaller work panes is common pattern
4. Backward Compatibility: Default tiled behavior remains unchanged if no layout specified

Additional Considerations

Pane Count Validation

• Verify layout file's pane count matches requested task count
• Provide clear error messages on mismatch

Terminal Size Handling

• Layout strings are terminal-size-dependent
• Consider storing layouts with size metadata or auto-scaling logic

Worktree Integration

• Ensure each pane in custom layouts receives proper worktree assignment
• Maintain worktree-to-pane mapping consistency

Real-World Use Case

Project: profile-web (Next.js monorepo migration)
Scenario: Parallel refactoring of 20+ components

Using 21-pane layout:

• Panes 1-20: Independent component refactoring tasks with isolated git worktrees
• Pane 21: Full-width monitoring pane for running tests, lint checks, and build status

This layout allows:

• Visual monitoring of all parallel tasks at a glance
• Dedicated space for aggregate feedback (test results, CI status)
• Quick navigation between isolated work contexts

Implementation Checklist

• Layout file loading and parsing
• Configuration schema for layout definitions
• CLI options: --layout, --layout-file, save-layout, list-layouts
• Pane count validation
• Integration with existing worktree assignment logic
• Documentation with common layout patterns
• Example layouts in repository

References

• tmux layout documentation: man tmux (WINDOWS AND PANES section)
• Layout strings: tmux display-message -p "#{window_layout}"
• Layout application: tmux select-layout "<layout-string>"