feat: tmuxinator/teamocil feature parity

[tony]

Summary

Bring tmuxp to feature parity with tmuxinator and teamocil. This adds the missing CLI commands, config keys, lifecycle hooks, config templating, and importer improvements that users migrating from those tools expect — plus comprehensive documentation including a full feature comparison page.

New CLI commands

tmuxp stop — kill a session with cleanup

$ tmuxp stop mysession

Runs the on_project_stop lifecycle hook before killing the session, giving projects a chance to tear down background services, save state, etc.

tmuxp new — create a workspace config

$ tmuxp new myproject

Creates a new workspace config from a minimal template and opens it in $EDITOR.

tmuxp copy — copy a workspace config

$ tmuxp copy myproject myproject-backup

Copies an existing workspace config to a new name. Source is resolved using the same logic as tmuxp load.

tmuxp delete — delete workspace configs

$ tmuxp delete old-project

Deletes workspace config files. Prompts for confirmation unless -y is passed.

Lifecycle hooks

Workspace configs now support four hooks, matching tmuxinator's hook system:

session_name: myproject
on_project_start: docker compose up -d
on_project_exit: docker compose down
on_project_stop: docker compose down -v
on_project_restart: echo "Reattaching..."
windows:
  - window_name: editor
    panes:
      - vim

Hook	When it runs
on_project_start	Before session build (every invocation)
on_project_restart	When reattaching to an existing session
on_project_exit	On client detach (via tmux client-detached hook)
on_project_stop	Before tmuxp stop kills the session

Config templating

Workspace configs now support {{ variable }} placeholders with values passed via --set:

# mytemplate.yaml
session_name: "{{ project }}"
start_directory: "~/code/{{ project }}"
windows:
  - window_name: editor
    panes:
      - vim

$ tmuxp load --set project=myapp mytemplate.yaml

New config keys

Pane titles

session_name: dashboard
enable_pane_titles: true
pane_title_position: top
pane_title_format: "#{pane_title}"
windows:
  - window_name: main
    panes:
      - title: logs
        shell_command: tail -f /var/log/syslog
      - title: editor
        shell_command: vim

synchronize shorthand

windows:
  - window_name: multi-server
    synchronize: before    # or: after, true
    panes:
      - ssh server1
      - ssh server2

Desugars synchronize: before → options: {synchronize-panes: on} and synchronize: after → options_after: {synchronize-panes: on}. true is equivalent to before.

shell_command_after and clear

windows:
  - window_name: dev
    shell_command_after:
      - echo "Window ready"
    clear: true
    panes:
      - vim
      - npm run dev

New tmuxp load flags

Flag	Description
--here	Reuse the current tmux window instead of creating a new session
--no-shell-command-before	Skip all shell_command_before entries
--debug	Show tmux commands as they execute (disables progress spinner)
--set KEY=VALUE	Pass template variables for config templating

Importer improvements

tmuxinator

• pre → on_project_start, pre_window → shell_command_before
• cli_args (-f, -S, -L) parsed into tmuxp equivalents
• synchronize window key converted
• startup_window / startup_pane → focus: true on the target
• Named panes (hash-key syntax) → title on the pane
• Window names coerced to str (fixes numeric/emoji YAML keys)

teamocil

• v1.x format support (windows at top level, commands key in panes)
• focus: true on windows and panes converted
• Window options passed through

Bug fixes

• Only fire on_project_start hook when load actually proceeds (not on cancellation)
• Only fire on_project_restart after the user confirms reattach

Documentation

• Feature comparison page (docs/comparison.md): Side-by-side of tmuxp vs tmuxinator vs teamocil — architecture, config keys, CLI flags, hooks
• Top-level config docs (docs/configuration/top-level.md): New keys, lifecycle hooks, synchronize, pane titles
• Config examples (docs/configuration/examples.md): Working examples for each new feature
• CLI docs: Pages for stop, new, copy, delete, plus updated load docs
• Import docs: Updated with notes on new importer capabilities

Test plan

• uv run py.test passes
• Tests for every new feature: stop, new, copy, delete, load flags, lifecycle hooks, config templating, builder, importers
• Importer fixtures for edge cases (numeric names, YAML aliases, named panes, v1.x teamocil format)
• Manual: tmuxp load with lifecycle hooks, --here, --debug, --set
• Manual: tmuxp stop, tmuxp new, tmuxp copy, tmuxp delete
• Manual: Import from tmuxinator/teamocil configs with new features

[codecov]

Codecov Report

❌ Patch coverage is 86.23327% with 72 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.95%. Comparing base (33da7da) to head (92ba6f4).

Files with missing lines	Patch %	Lines
src/tmuxp/cli/load.py	68.08%	24 Missing and 6 partials ⚠️
src/tmuxp/workspace/builder.py	82.22%	9 Missing and 7 partials ⚠️
src/tmuxp/workspace/importers.py	88.54%	5 Missing and 10 partials ⚠️
src/tmuxp/cli/copy.py	86.11%	3 Missing and 2 partials ⚠️
src/tmuxp/cli/delete.py	89.28%	2 Missing and 1 partial ⚠️
src/tmuxp/util.py	88.23%	2 Missing ⚠️
src/tmuxp/workspace/loader.py	97.56%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1025      +/-   ##
==========================================
+ Coverage   81.01%   81.95%   +0.93%     
==========================================
  Files          28       32       +4     
  Lines        2629     3087     +458     
  Branches      492      601     +109     
==========================================
+ Hits         2130     2530     +400     
- Misses        368      408      +40     
- Partials      131      149      +18     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tony]

Code review

Found 4 issues:

1. Shell command injection via start_directory in --here mode. The --here path constructs f'cd "{start_directory}"' and sends it as keystrokes via send_keys. A start_directory containing " or ; can inject arbitrary shell commands into the pane. The non---here path safely passes start_directory as a structured argument to new_window(). Consider using shlex.quote() or passing the directory through tmux's -c flag instead.

tmuxp/src/tmuxp/workspace/builder.py

Lines 674 to 680 in db303db

	if start_directory:
	active_pane = window.active_pane
	if active_pane is not None:
	active_pane.send_keys(
	f'cd "{start_directory}"',
	enter=True,
	)

2. Missing doctests on command_copy, command_delete, command_new, command_stop (CLAUDE.md says "All functions and methods MUST have working doctests.")

tmuxp/src/tmuxp/cli/copy.py

Lines 82 to 88 in db303db

	def command_copy(
	source: str,
	destination: str,
	parser: argparse.ArgumentParser | None = None,
	color: CLIColorModeLiteral | None = None,
	) -> None:
	"""Entrypoint for ``tmuxp copy``, copy a workspace config to a new name."""

tmuxp/src/tmuxp/cli/delete.py

Lines 81 to 88 in db303db

	def command_delete(
	workspace_names: list[str],
	answer_yes: bool = False,
	parser: argparse.ArgumentParser | None = None,
	color: CLIColorModeLiteral | None = None,
	) -> None:
	"""Entrypoint for ``tmuxp delete``, remove workspace config files."""
	color_mode = get_color_mode(color)

tmuxp/src/tmuxp/cli/new.py

Lines 81 to 88 in db303db

	def command_new(
	workspace_name: str,
	parser: argparse.ArgumentParser | None = None,
	color: CLIColorModeLiteral | None = None,
	) -> None:
	"""Entrypoint for ``tmuxp new``, create a new workspace config from template."""
	color_mode = get_color_mode(color)
	colors = Colors(color_mode)

tmuxp/src/tmuxp/cli/stop.py

Lines 82 to 88 in db303db

	def command_stop(
	args: CLIStopNamespace,
	parser: argparse.ArgumentParser | None = None,
	) -> None:
	"""Entrypoint for ``tmuxp stop``, kill a tmux session."""
	color_mode = get_color_mode(args.color)
	colors = Colors(color_mode)

3. Missing doctest on _load_here_in_current_session (CLAUDE.md says "All functions and methods MUST have working doctests.")

tmuxp/src/tmuxp/cli/load.py

Lines 326 to 334 in db303db

	def _load_here_in_current_session(builder: WorkspaceBuilder) -> None:
	"""Load workspace reusing current window for first window.
	Parameters
	----------
	builder: :class:`workspace.builder.WorkspaceBuilder`
	"""
	current_attached_session = builder.find_current_attached_session()
	builder.build(current_attached_session, here=True)

4. socket_name extracted from cli_args: "-L mysocket" is silently overwritten if the tmuxinator config also has an explicit socket_name key. The -L value is parsed at line 103, then unconditionally replaced at lines 105-106. Consider only overwriting if the explicit key exists and differs, or logging a warning about the conflict.

tmuxp/src/tmuxp/workspace/importers.py

Lines 93 to 107 in db303db

	raw_args = workspace_dict.get("cli_args") or workspace_dict.get("tmux_options")
	if raw_args:
	tokens = shlex.split(raw_args)
	flag_map = {"-f": "config", "-L": "socket_name", "-S": "socket_path"}
	it = iter(tokens)
	for token in it:
	if token in flag_map:
	value = next(it, None)
	if value is not None:
	tmuxp_workspace[flag_map[token]] = value
	if "socket_name" in workspace_dict:
	tmuxp_workspace["socket_name"] = workspace_dict["socket_name"]

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[tony]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

Review scope (5 parallel agents):

1. CLAUDE.md compliance audit — 4 minor findings, all below confidence threshold after scoring
2. Shallow bug scan — 3 candidates; 1 debunked (shlex.quote + replace is valid POSIX quoting), 1 confirmed as correct tmuxinator parity, 1 edge case with adequate logging
3. Git history context — no regressions found vs. prior commits
4. Prior PR comments — color hierarchy and prompt patterns from PRs CLI Colors #1006/feat(load): animated progress spinner for tmuxp load #1020 verified compliant
5. Code comments compliance — 1 stale docstring (pre-existing, not introduced by this PR)

Prior review rounds: 3 rounds of 3-model (Claude/Gemini/GPT) loom reviews found 16 issues, all fixed in subsequent commits on this branch.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}