tmuxinator/teamocil feature parity

[tony]

Status (2026-03-15): All libtmux blockers resolved — libtmux#635 is closed. L1, L2, L3 all shipped in libtmux v0.55.0 (2026-03-07). tmuxp pins libtmux~=0.55.0. Phase 1 (import fixes) is complete (7/7 items, 21 tests pass). All remaining work is purely tmuxp-side — zero libtmux dependencies remain.

Summary

Tracking issue for reaching feature parity with tmuxinator (3.3.7) and teamocil (1.4.2). Based on a comprehensive source-level analysis of both projects, their importers, and the tmuxp builder/loader/CLI.

Tracking issue for libtmux-side API additions: tmux-python/libtmux#635

---

Phase 1: Import Fixes (No Builder/libtmux Changes) — COMPLETE

All 7 items done, 21 tests pass.

• I1. tmuxinator pre / pre_window mapping bugs — fixed pre → before_script, pre_window → shell_command_before (1967487a)
• I2. tmuxinator cli_args / tmux_options fragile parsing — use shlex.split() for flag-aware parsing (e8016019)
• I3. teamocil redundant filter loops — replace with direct assignment (f61343a3)
• I4. teamocil v1.x format support — string panes, commands key (f61343a3)
• I5. tmuxinator missing keys — rvm, pre_tab, startup_window, startup_pane, synchronize (5cb75946)
• I6. teamocil missing keys — focus, options, height handling (466fc9b2)
• I7. Importer TODOs — logging for unsupported/dropped keys, remove stale TODOs (74656db5)

---

Phase 2: Builder Additions (tmuxp Only)

T1. No synchronize Config Key

• Desugared — importer maps synchronize: true/before → options: {synchronize-panes: on} and synchronize: after → options_after: {synchronize-panes: on}. Builder already handles both options and options_after. No builder change needed.

T3. No shell_command_after Config Key

• Teamocil importer produces shell_command_after (from filters.after), but builder never reads it.
• Implementation: Read window_config.get("shell_command_after", []) in config_after_window() and send to panes. ~5 lines.

T2. No Pane Title Config Key — NOW UNBLOCKED

• Previously blocked on L1 — now resolved. Pane.set_title(title) available in libtmux v0.55.0.
• Implementation: Session-level enable_pane_titles, pane_title_position, pane_title_format via session.set_option(). Per-pane title via pane.set_title(). Update tmuxinator importer for named pane syntax (pane_name: command → title + shell_command).

T4. No Session Rename Mode / --here CLI Flag

• tmuxp load has no --here flag. Always creates new windows.
• Implementation: Add --here to cli/load.py. For first window: rename_window() + send_keys("cd <root>") instead of new_window(). Also rename_session() when --here is used.

Dead Config Keys

• Pop+warn for socket_name, config, target
• Implement clear in builder (use pane.clear())
• Implement start_window/start_pane in builder (select matching window/pane after build)

---

Phase 3: libtmux Additions — COMPLETE

All items shipped in libtmux v0.55.0 (2026-03-07). Issue libtmux#635 is closed.

• L1. Pane.set_title(title) — pane.py:834-859 (unblocks T2)
• L2. Server(tmux_bin=...) — server.py:131-146 (unblocks tmuxinator tmux_command)
• L3. Pre-execution logger.debug — common.py:263-268 (unblocks T9)

---

Phase 4: New CLI Commands

T5. No stop / kill CLI Command

• tmuxp has no stop command. Add tmuxp stop <session> — find session, call session.kill(). Run on_project_stop hook before kill.

T10. Missing Config Management Commands

• Missing: new, copy, delete. Straightforward file operations.

---

Phase 5: CLI Flags & Larger Features

T7. --no-shell-command-before CLI Flag

• Skip shell_command_before for debugging. Equivalent to tmuxinator --no-pre-window. Simple flag addition.

T9. --debug / Dry-Run CLI Flag — NOW UNBLOCKED

• Previously blocked on L3 — now resolved. Pre-execution logging available in libtmux v0.55.0.
• Implementation: Add --debug flag to cli/load.py. Capture DEBUG-level log output from libtmux to show tmux commands that would be executed.

T6. No Lifecycle Hook Config Keys

• Config-driven shell command hooks (on_project_start, on_project_exit, etc.). Complex, needs design. Depends on T5 for on_project_stop.

T8. Config Templating

• User-defined variable interpolation (Jinja2 or string.Template). Significant architectural addition.

---

Dead Config Keys

Keys produced by importers but silently ignored by the builder:

Key	Producer	Issue
config	tmuxinator	Dead data — extracted -f path unused
socket_name	tmuxinator	Dead data — CLI uses -L flag
clear	teamocil	Builder doesn't read it (libtmux has Pane.clear())
target (pane)	teamocil	Accidentally preserved (libtmux has Pane.split(target=...))
shell_command_after	teamocil	Builder has no after-command support (T3)

Progress Summary

Phase	Status	Items
Phase 1: Import Fixes	COMPLETE	7/7
Phase 2: Builder Additions	In progress	1/5 done (T1 desugared)
Phase 3: libtmux Additions	COMPLETE	3/3
Phase 4: CLI Commands	Not started	0/2
Phase 5: CLI Flags & Features	Not started	0/4