tmux-python · tony · Feb 8, 2026 · Feb 8, 2026 · Feb 8, 2026 · Feb 8, 2026
diff --git a/.gitignore b/.gitignore
@@ -88,3 +88,7 @@ docs/_static/css/fonts.css
 **/CLAUDE.local.md
 **/CLAUDE.*.md
 **/.claude/settings.local.json
+.claude/commands/
+
+# Development notes
+notes/
diff --git a/CHANGES b/CHANGES
@@ -33,11 +33,95 @@ $ pipx install \
 
 ## tmuxp 1.68.0 (Yet to be released)
 
-<!-- To maintainers and contributors: Please add notes for the forthcoming version below -->
+### New commands
 
-<!-- KEEP THIS PLACEHOLDER - DO NOT REMOVE OR MODIFY THIS LINE -->
-_Notes on the upcoming release will go here._
-<!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
+#### `tmuxp stop` — kill a tmux session (#1025)
+Stop (kill) a running tmux session by name. Runs the `on_project_stop`
+lifecycle hook before killing the session, giving your project a chance
+to clean up.
+
+```console
+$ tmuxp stop mysession
+```
+
+#### `tmuxp new` — create a workspace config (#1025)
+Create a new workspace configuration file from a minimal template and
+open it in `$EDITOR`.
+
+```console
+$ tmuxp new myproject
+```
+
+#### `tmuxp copy` — copy a workspace config (#1025)
+Copy an existing workspace config to a new name. Source is resolved
+using the same logic as `tmuxp load`.
+
+```console
+$ tmuxp copy myproject myproject-backup
+```
+
+#### `tmuxp delete` — delete workspace configs (#1025)
+Delete one or more workspace config files. Prompts for confirmation
+unless `-y` is passed.
+
+```console
+$ tmuxp delete old-project
+```
+
+### Lifecycle hooks (#1025)
+Workspace configs now support four lifecycle hooks inspired by tmuxinator:
+
+- `on_project_start` — runs before session build (new session creation only)
+- `on_project_restart` — runs when reattaching to an existing session (confirmed attach only)
+- `on_project_exit` — runs when the last client detaches (via tmux `client-detached` hook)
+- `on_project_stop` — runs before `tmuxp stop` kills the session
+
+### Config templating (#1025)
+Workspace configs now support simple `{{ variable }}` placeholders for variable substitution.
+Pass values via `--set KEY=VALUE` on the command line:
+
+```console
+$ tmuxp load --set project=myapp mytemplate.yaml
+```
+
+### New config keys (#1025)
+- **`enable_pane_titles`** / **`pane_title_position`** / **`pane_title_format`** —
+  session-level keys that enable tmux pane border titles.
+- **`title`** — pane-level key to set individual pane titles via
+  `select-pane -T`.
+- **`synchronize`** — window-level shorthand (`before` / `after` / `true`)
+  that sets `synchronize-panes` without needing `options_after`.
+- **`shell_command_after`** — window-level key; commands sent to every pane
+  after the window is fully built.
+- **`clear`** — window-level boolean; sends `clear` to every pane after
+  commands complete.
+
+### New `tmuxp load` flags (#1025)
+- `--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 (#1025)
+#### tmuxinator
+
+- Map `pre` → `on_project_start`, `pre_window` → `shell_command_before`.
+- Parse `cli_args` (`-f`, `-S`, `-L`) into tmuxp equivalents.
+- Convert `synchronize` window key.
+- Convert `startup_window` / `startup_pane` → `focus: true`.
+- Convert named panes (hash-key syntax) → `title` on the pane.
+
+#### teamocil
+
+- Support v1.x format (`windows` at top level, `commands` key in panes).
+- Convert `focus: true` on windows and panes.
+- Pass through window `options`.
+
+### Bug fixes
+
+- Only fire `on_project_start` hook when load actually proceeds (not on
+  cancellation) (#1025)
+- Only fire `on_project_restart` after the user confirms reattach (#1025)
 
 ## tmuxp 1.67.0 (2026-03-08)
 

diff --git a/conftest.py b/conftest.py
@@ -100,6 +100,9 @@ def socket_name(request: pytest.FixtureRequest) -> str:
 
 # Modules that actually need tmux fixtures in their doctests
 DOCTEST_NEEDS_TMUX = {
+    "tmuxp.cli.load",
+    "tmuxp.cli.stop",
+    "tmuxp.util",
     "tmuxp.workspace.builder",
 }
 

diff --git a/docs/cli/copy.md b/docs/cli/copy.md
@@ -0,0 +1,25 @@
+(cli-copy)=
+
+(cli-copy-reference)=
+
+# tmuxp copy
+
+Copy an existing workspace config to a new name. Source is resolved using the same logic as `tmuxp load` (supports names, paths, and extensions).
+
+## Command
+
+```{eval-rst}
+.. argparse::
+    :module: tmuxp.cli
+    :func: create_parser
+    :prog: tmuxp
+    :path: copy
+```
+
+## Basic usage
+
+Copy a workspace:
+
+```console
+$ tmuxp copy myproject myproject-backup
+```
diff --git a/docs/cli/delete.md b/docs/cli/delete.md
@@ -0,0 +1,37 @@
+(cli-delete)=
+
+(cli-delete-reference)=
+
+# tmuxp delete
+
+Delete one or more workspace config files. Prompts for confirmation unless `-y` is passed.
+
+## Command
+
+```{eval-rst}
+.. argparse::
+    :module: tmuxp.cli
+    :func: create_parser
+    :prog: tmuxp
+    :path: delete
+```
+
+## Basic usage
+
+Delete a workspace:
+
+```console
+$ tmuxp delete old-project
+```
+
+Delete without confirmation:
+
+```console
+$ tmuxp delete -y old-project
+```
+
+Delete multiple workspaces:
+
+```console
+$ tmuxp delete proj1 proj2
+```
diff --git a/docs/cli/import.md b/docs/cli/import.md
@@ -38,6 +38,14 @@ $ tmuxp import teamocil /path/to/file.json
 
 ````
 
+### Importer improvements
+
+The teamocil importer now supports:
+
+- **v1.x format** — `windows` at top level with `commands` key in panes
+- **Focus** — `focus: true` on windows and panes is preserved
+- **Window options** — `options` on windows are passed through
+
 (import-tmuxinator)=
 
 ## From tmuxinator
@@ -71,3 +79,13 @@ $ tmuxp import tmuxinator /path/to/file.json
 ```
 
 ````
+
+### Importer improvements
+
+The tmuxinator importer now supports:
+
+- **Hook mapping** — `pre` maps to `on_project_start`, `pre_window` maps to `shell_command_before`
+- **CLI args** — `cli_args` values (`-f`, `-S`, `-L`) are parsed into tmuxp config equivalents
+- **Synchronize** — `synchronize` window key is converted
+- **Startup focus** — `startup_window` / `startup_pane` convert to `focus: true`
+- **Named panes** — hash-key pane syntax converts to `title` on the pane
diff --git a/docs/cli/index.md b/docs/cli/index.md
@@ -53,6 +53,7 @@ load
 shell
 ls
 search
+stop
 ```
 
 ```{toctree}
@@ -63,6 +64,9 @@ edit
 import
 convert
 freeze
+new
+copy
+delete
 ```
 
 ```{toctree}

diff --git a/docs/cli/load.md b/docs/cli/load.md
@@ -253,3 +253,67 @@ When progress is disabled, logging flows normally to the terminal and no spinner
 ### Before-script behavior
 
 During `before_script` execution, the progress bar shows a marching animation and a ⏸ status icon, indicating that tmuxp is waiting for the script to finish before continuing with pane creation.
+
+## Here mode
+
+The `--here` flag reuses the current tmux window instead of creating a new session. This is similar to teamocil's `--here` flag.
+
+```console
+$ tmuxp load --here .
+```
+
+When used, tmuxp builds the workspace panes inside the current window rather than spawning a new session.
+
+`--here` only supports a single workspace file per invocation.
+
+```{note}
+When `--here` needs to provision a directory, environment, or shell, tmuxp uses tmux primitives (`set-environment` and `respawn-pane`) instead of typing `cd` / `export` into the pane. If provisioning is needed, tmux will replace the active pane process before the workspace commands run, so long-running child processes in that pane can be terminated.
+```
+
+## Skipping shell_command_before
+
+The `--no-shell-command-before` flag skips all `shell_command_before` entries at every level (session, window, pane). This is useful for quick reloads when the setup commands (virtualenv activation, etc.) are already active.
+
+```console
+$ tmuxp load --no-shell-command-before myproject
+```
+
+```{note}
+This flag is intentionally broader than tmuxinator's `--no-pre-window`, which only disables the window-level `pre_window` chain. tmuxp's flag strips `shell_command_before` at all levels for a clean reload experience.
+```
+
+## Debug mode
+
+The `--debug` flag shows tmux commands as they execute. This disables the progress spinner and attaches a debug handler to libtmux's logger, printing each tmux command to stdout.
+
+```console
+$ tmuxp load --debug myproject
+```
+
+## Config templating
+
+Workspace configs support simple `{{ variable }}` placeholders for variable substitution. Pass values via `--set KEY=VALUE`:
+
+```console
+$ tmuxp load --set project=myapp mytemplate.yaml
+```
+
+Multiple variables can be passed:
+
+```console
+$ tmuxp load --set project=myapp --set env=staging mytemplate.yaml
+```
+
+In the config file, use double-brace syntax:
+
+```yaml
+session_name: "{{ project }}"
+windows:
+  - window_name: "{{ project }}-main"
+    panes:
+      - echo "Working on {{ project }}"
+```
+
+```{note}
+Values containing `{{ }}` must be quoted in YAML to avoid parse errors.
+```
diff --git a/docs/cli/new.md b/docs/cli/new.md
@@ -0,0 +1,25 @@
+(cli-new)=
+
+(cli-new-reference)=
+
+# tmuxp new
+
+Create a new workspace configuration file from a minimal template and open it in `$EDITOR`. If the workspace already exists, it opens for editing.
+
+## Command
+
+```{eval-rst}
+.. argparse::
+    :module: tmuxp.cli
+    :func: create_parser
+    :prog: tmuxp
+    :path: new
+```
+
+## Basic usage
+
+Create a new workspace:
+
+```console
+$ tmuxp new myproject
+```
diff --git a/docs/cli/stop.md b/docs/cli/stop.md
@@ -0,0 +1,37 @@
+(cli-stop)=
+
+(cli-stop-reference)=
+
+# tmuxp stop
+
+Stop (kill) a running tmux session. If `on_project_stop` is defined in the workspace config, that hook runs before the session is killed.
+
+## Command
+
+```{eval-rst}
+.. argparse::
+    :module: tmuxp.cli
+    :func: create_parser
+    :prog: tmuxp
+    :path: stop
+```
+
+## Basic usage
+
+Stop a session by name:
+
+```console
+$ tmuxp stop mysession
+```
+
+Stop the currently attached session:
+
+```console
+$ tmuxp stop
+```
+
+Use a custom socket:
+
+```console
+$ tmuxp stop -L mysocket mysession
+```
-Original file line number
+Diff line change
@@ Expand Up / @@ -53,6 +53,7 @@ load @@
     shell
     ls
     search
+    stop
     ```
     ```{toctree}
@@ Expand All / @@ -63,6 +64,9 @@ edit @@
     import
     convert
     freeze
+    new
+    copy
+    delete
     ```
     ```{toctree}
@@ Expand Down @@