Feature Request: Custom Layout Support for Multi-Pane Setups

[JeremyDev87]

Feature Request: Custom Layout Support for Multi-Pane Setups

Summary

Add support for saving and restoring custom tmux pane layouts in TaskMaestro, allowing users to define and reuse their preferred grid configurations.

Use Case

When working with 20 parallel tasks (like code refactoring across multiple modules), I need a consistent 4x5 grid layout with a dedicated conductor pane at the bottom:

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

Current Behavior:

• TaskMaestro creates panes dynamically but doesn't preserve specific layouts
• Users must manually recreate their preferred grid structure each time
• tmux layout strings are not saved or managed by TaskMaestro

Desired Behavior:

• Save current layout: /taskmaestro layout save <name>
• Load saved layout: /taskmaestro start --layout <name>
• List saved layouts: /taskmaestro layout list
• Delete layout: /taskmaestro layout delete <name>

Proposed Implementation

1. Layout Storage

Store layouts in ~/.claude/taskmaestro-layouts.json:

{
  "grid-4x5": {
    "name": "grid-4x5",
    "description": "4 rows × 5 columns + conductor",
    "pane_count": 21,
    "layout_string": "a61f,375x90,0,0[...]",
    "conductor_pane": 21,
    "created_at": "2026-03-23T10:00:00Z"
  }
}

2. New Commands

Save Layout

/taskmaestro layout save <name> [--description "..."]

• Captures current window layout via tmux list-windows -F '#{window_layout}'
• Stores pane count, layout string, and conductor pane index
• Validates layout can be restored

Load Layout on Start

/taskmaestro start --layout <name>

• Creates or adjusts panes to match saved count
• Applies saved layout string via tmux select-layout
• Falls back to tiled if layout string fails

List Layouts

/taskmaestro layout list

Output:

Available Layouts:

  grid-4x5 (21 panes)
    4 rows × 5 columns + conductor
    Created: 2026-03-23

  grid-2x3 (7 panes)
    2 rows × 3 columns + conductor
    Created: 2026-03-22

Delete Layout

/taskmaestro layout delete <name>

3. Backward Compatibility

• start without --layout continues current behavior (tiled)
• Layouts are optional feature, not required for basic usage

Benefits

1. Consistency: Same visual structure across sessions
2. Productivity: No manual pane arrangement needed
3. Flexibility: Support different layouts for different task types (3-pane for small tasks, 20-pane for large parallel work)
4. Portability: Share layout configs across machines via dotfiles

Example Workflow

# First time: Set up preferred layout manually, then save
/taskmaestro start
# (arrange panes into 4x5 grid + conductor)
/taskmaestro layout save grid-4x5 --description "Parallel tidying layout"

# Future sessions: Instantly restore layout
/taskmaestro start --layout grid-4x5

Technical Details

Layout String Format

tmux layout strings encode:

• Pane arrangement (splits, dimensions)
• Relative positions and sizes
• Example: a61f,375x90,0,0[375x17,0,0{74x17,0,0,1,...},...]

Implementation Notes

• Layout strings are terminal size dependent
• Fallback to tiled if dimensions don't match
• Option to scale layout proportionally to current terminal size

Alternative Approach

If layout strings prove too fragile, consider a declarative approach:

{
  "type": "grid",
  "rows": 4,
  "cols": 5,
  "footer": true,
  "footer_height_percent": 20
}

This would procedurally generate layouts that adapt to any terminal size.

Related

• tmux layout documentation: man tmux → WINDOWS AND PANES
• Similar feature in tmuxinator (different scope)

---

Environment:

• TaskMaestro: Current version
• tmux: 3.5+
• Platform: macOS/Linux

Happy to help implement this if the approach sounds good! 🚀