Plugins¶

Plugins let you customize and extend how tmuxp builds a session — renaming it, reacting when you reattach, running setup at specific moments — without forking tmuxp or hand-editing your workspace files. This is an advanced, opt-in feature: most users never write or install one, and a workspace loads exactly the same with no plugins at all. Reach for a plugin when you want behavior the workspace format can’t express and you’re comfortable writing a little Python.

Using a plugin¶

Install the plugin into the same Python environment as tmuxp, then name it in your workspace file under plugins:

YAML

session_name: plugin-system
plugins:
  - "tmuxp_plugin_extended_build.plugin.PluginExtendedBuild"
windows:
  - window_name: editor
    layout: tiled
    shell_command_before:
      - cd ~/
    panes:
      - shell_command:
          - cd /var/log
          - ls -al | grep *.log
      - echo "hello world"

JSON

{
  "session_name": "plugin-system",
  "plugins": [
    "tmuxp_plugin_extended_build.plugin.PluginExtendedBuild"
  ],
  "windows": [
    {
      "window_name": "editor",
      "layout": "tiled",
      "shell_command_before": [
        "cd ~/"
      ],
      "panes": [
        {
          "shell_command": [
            "cd /var/log",
            "ls -al | grep *.log"
          ]
        },
        "echo \"hello world\""
      ]
    }
  ]
}

When your hooks fire¶

A plugin is a class whose methods tmuxp calls at set points while it builds and attaches the session. You override only the hooks you care about; the rest do nothing. tmuxp load drives the lifecycle in a fixed order:

When each plugin hook fires.

before_workspace_builder() runs first, once the session exists but before any windows. on_window_create() and after_window_finished() bracket each window’s panes. Two of the names can mislead: before_script() runs after the whole session is built — it augments, rather than replaces, the workspace’s own before_script — and reattach() fires only when tmuxp re-attaches you to a session that already exists.

Developing a plugin¶

tmuxp expects a plugin to be a class in a Python submodule named plugin, inside a module installed in the same environment as tmuxp. You inherit from the interface tmuxp provides, TmuxpPlugin.

uv is tmuxp’s package manager of choice, and what these examples use; pip works just as well. You need only one project file, for whichever packaging tool you choose.

python_module
├── tmuxp_plugin_my_plugin_module
│   ├── __init__.py
│   └── plugin.py
└── pyproject.toml  # Python project configuration file

When publishing to PyPI, tmuxp suggests the naming convention tmuxp-plugin-{your-plugin-name} so others can find it. A minimal pyproject.toml looks like this:

[project]
name = "tmuxp-plugin-my-tmuxp-plugin"
version = "0.0.2"
description = "An example tmuxp plugin."
authors = [{ name = "Author Name", email = "[email protected]" }]
requires-python = ">=3.10"
dependencies = [
  "tmuxp>=1.7.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

The plugin.py file holds the class:

import datetime

from tmuxp.plugin import TmuxpPlugin


class MyTmuxpPlugin(TmuxpPlugin):
    def __init__(self):
        """Initialize my custom plugin."""
        # Optional version-dependency configuration. See the Plugin API
        # docs for every supported parameter.
        config = {
            'tmuxp_min_version': '1.6.2',
        }

        TmuxpPlugin.__init__(
            self,
            plugin_name='tmuxp-plugin-my-tmuxp-plugin',
            **config,
        )

    def before_workspace_builder(self, session):
        session.rename_session('my-new-session-name')

    def reattach(self, session):
        now = datetime.datetime.now().strftime('%Y-%m-%d')
        session.rename_session('session_{}'.format(now))

Once it’s installed in the same environment, name it in a workspace file:

session_name: plugin example
plugins:
  - my_plugin_module.plugin.MyTmuxpPlugin
# ... the rest of your workspace

Plugin API¶

TmuxpPlugin.__init__(**kwargs)
¶
method[source]
method[source]
TmuxpPlugin.__init__(**kwargs)
¶

Initialize plugin.

The default version values are set to the versions that the plugin system requires.

Parameters:

plugin_name (str) – Name of the child plugin. Used in error message plugin fails to load
tmux_min_version (str) – Min version of tmux that the plugin supports
tmux_max_version (str) – Min version of tmux that the plugin supports
tmux_version_incompatible (list) – Versions of tmux that are incompatible with the plugin
libtmux_min_version (str) – Min version of libtmux that the plugin supports
libtmux_max_version (str) – Max version of libtmux that the plugin supports
libtmux_version_incompatible (list) – Versions of libtmux that are incompatible with the plugin
tmuxp_min_version (str) – Min version of tmuxp that the plugin supports
tmuxp_max_version (str) – Max version of tmuxp that the plugin supports
tmuxp_version_incompatible (list) – Versions of tmuxp that are incompatible with the plugin
kwargs (Unpack[PluginConfigSchema])

Return type:

None

TmuxpPlugin.before_workspace_builder(session) ¶ method[source] method[source] TmuxpPlugin.before_workspace_builder(session) ¶

Provide a session hook previous to creating the workspace.

This runs after the session has been created but before any of the windows/panes/commands are entered.

Parameters:: session (libtmux.Session) – session to hook into
Return type:: None

TmuxpPlugin.on_window_create(window) ¶ method[source] method[source] TmuxpPlugin.on_window_create(window) ¶

Provide a window hook previous to doing anything with a window.

This runs runs before anything is created in the windows, like panes.

Parameters:: window (libtmux.Window) – window to hook into
Return type:: None

TmuxpPlugin.after_window_finished(window) ¶ method[source] method[source] TmuxpPlugin.after_window_finished(window) ¶

Provide a window hook after creating the window.

This runs after everything has been created in the window, including the panes and all of the commands for the panes. It also runs after the options_after has been applied to the window.

Parameters:: window (libtmux.Window) – window to hook into
Return type:: None

TmuxpPlugin.before_script(session) ¶ method[source] method[source] TmuxpPlugin.before_script(session) ¶

Provide a session hook after the workspace has been built.

This runs after the workspace has been loaded with tmuxp load. It augments instead of replaces the before_script section of the workspace data.

This hook provides access to the LibTmux.session object for any behavior that would be used in the before_script section of the workspace file that needs access directly to the session object. This runs after the workspace has been loaded with tmuxp load.

The hook augments, rather than replaces, the before_script section of the workspace. While it is possible to do all of the before_script workspace in this function, if a shell script is currently being used for the workspace, it would be cleaner to continue using the script in the before_section.

If changes to the session need to be made prior to anything being built, please use before_workspace_builder() instead.

Parameters:: session (libtmux.Session) – session to hook into
Return type:: None

TmuxpPlugin.reattach(session) ¶ method[source] method[source] TmuxpPlugin.reattach(session) ¶

Provide a session hook before reattaching to the session.

Parameters:: session (libtmux.Session) – session to hook into
Return type:: None