Workspace(feat[runtime]): Add pane title and synchronization keys

CHANGES

@@ -44,6 +44,23 @@ $ tmuxp@next load yoursession
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### What's new
+
+#### Pane titles (#1047)
+
+Workspace configs can label panes natively: session-level
+`enable_pane_titles`, `pane_title_position`, and `pane_title_format`
+turn on tmux's pane border titles, and a pane-level `title` names
+individual panes — replacing the escape-sequence workaround previously
+required. See {ref}`top-level` for examples.
+
+#### New window keys: `synchronize`, `shell_command_after`, `clear` (#1047)
+
+`synchronize` sets the final pane synchronization state while tmuxp keeps
+setup and post-build commands isolated per pane; `shell_command_after` runs
+commands in every pane after the window is built; `clear: true` clears each
+pane once its commands complete. See {ref}`top-level`.
+
 ## tmuxp 1.70.0 (2026-05-23)
 
 tmuxp 1.70.0 bumps libtmux to 0.58.0, fixing session and window listing on systems whose locale is not UTF-8.

docs/configuration/examples.md

@@ -533,9 +533,10 @@ Including `automatic-rename`, `default-shell`,
 
 ## Set window options after pane creation
 
-Apply window options after panes have been created. Useful for
-`synchronize-panes` option after executing individual commands in each
-pane during creation.
+Apply window options after panes have been created. When
+`synchronize-panes` appears in `options` or `options_after`, tmuxp keeps it
+disabled while sending configured commands and restores the requested final
+state after the window is ready.
 
 ````{tab} YAML
 ```{literalinclude} ../../examples/2-pane-synchronized.yaml
@@ -785,6 +786,29 @@ windows:
 [poetry]: https://python-poetry.org/
 [uv]: https://github.com/astral-sh/uv
 
+## Synchronize Panes Shorthand
+
+The `synchronize` window key provides a shorthand for the final
+`synchronize-panes` state without spelling out tmux options directly:
+
+````{tab} YAML
+```{literalinclude} ../../examples/synchronize-shorthand.yaml
+:language: yaml
+
+```
+````
+
+## Pane Titles
+
+Pane title keys turn on tmux pane border titles and label individual panes:
+
+````{tab} YAML
+```{literalinclude} ../../examples/pane-titles.yaml
+:language: yaml
+
+```
+````
+
 ## Kung fu
 
 :::{note}

docs/configuration/top-level.md

@@ -40,3 +40,112 @@ Notes:
   ```
 
   Above: Use `tmux` directly to attach _banana_.
+
+## Pane Titles
+
+Enable pane border titles to display labels on each pane:
+
+```yaml
+session_name: myproject
+enable_pane_titles: true
+pane_title_position: top
+pane_title_format: "#{pane_index}: #{pane_title}"
+windows:
+  - window_name: dev
+    panes:
+      - title: editor
+        shell_command:
+          - vim
+      - title: tests
+        shell_command:
+          - uv run pytest --watch
+      - shell_command:
+          - git status
+```
+
+| Key | Level | Description |
+|-----|-------|-------------|
+| `enable_pane_titles` | session | Enable pane border titles (`true` or `false`). |
+| `pane_title_position` | session | Position of the title bar (`top`, `bottom`, or `off`). |
+| `pane_title_format` | session | Format string using tmux variables. |
+| `title` | pane | Title text for an individual pane. |
+
+```{note}
+tmux ignores empty pane titles — `title: ""` logs a warning and keeps the
+default label. Use a single space (`title: " "`) to visually blank one.
+```
+
+## synchronize
+
+Window-level shorthand for the final `synchronize-panes` state. tmuxp keeps
+pane synchronization disabled while it builds panes and sends configured
+commands, then restores the requested synchronized state after the window is
+ready.
+
+```yaml
+session_name: sync-demo
+windows:
+  - window_name: synced
+    synchronize: after
+    panes:
+      - echo pane0
+      - echo pane1
+  - window_name: not-synced
+    panes:
+      - echo pane0
+      - echo pane1
+```
+
+| Value | Behavior |
+|-------|----------|
+| `after` | Synchronize panes after tmuxp finishes building the window. |
+| `before` | Compatibility alias for the same final synchronized state. |
+| `true` | Compatibility alias for the same final synchronized state. |
+| `false` | Force the final window state to unsynchronized. |
+
+## shell_command_after
+
+Window-level commands sent to every pane after all panes have been created and
+their individual commands executed:
+
+```yaml
+session_name: myproject
+windows:
+  - window_name: servers
+    shell_command_after:
+      - echo "All panes ready"
+    panes:
+      - ./start-api.sh
+      - ./start-worker.sh
+```
+
+tmuxp keeps `synchronize-panes` disabled while `shell_command_after` runs, then
+restores the final synchronized state afterward. This prevents tmux from
+duplicating post-build commands across panes.
+
+Entries accept the same command mappings as `shell_command` — `enter`,
+`sleep_before`, and `sleep_after` apply per command (sleeps run once per
+command, before and after it is sent to every pane):
+
+```yaml
+shell_command_after:
+  - cmd: ./healthcheck.sh
+    sleep_before: 2
+  - cmd: tail -f app.log
+    enter: false
+```
+
+## clear
+
+Window-level boolean. When `true`, sends `clear` to every pane after all
+commands, including `shell_command_after`, have completed:
+
+```yaml
+session_name: myproject
+windows:
+  - window_name: dev
+    clear: true
+    panes:
+      - cd src
+      - cd tests
+```

examples/pane-titles.yaml

@@ -0,0 +1,15 @@
+session_name: pane titles
+enable_pane_titles: true
+pane_title_position: top
+pane_title_format: "#{pane_index}: #{pane_title}"
+windows:
+  - window_name: titled
+    panes:
+      - title: editor
+        shell_command:
+          - echo pane0
+      - title: runner
+        shell_command:
+          - echo pane1
+      - shell_command:
+          - echo pane2

examples/synchronize-shorthand.yaml

@@ -0,0 +1,17 @@
+session_name: synchronize shorthand
+windows:
+  - window_name: synced-after
+    synchronize: after
+    panes:
+      - echo 0
+      - echo 1
+  - window_name: synced-compat-before
+    synchronize: before
+    panes:
+      - echo 0
+      - echo 1
+  - window_name: not-synced
+    synchronize: false
+    panes:
+      - echo 0
+      - echo 1