tmux-python/tmuxp

📦 Dependencies

• Minimum `libtmux~=0.58.1` (was `~=0.58.0`) (#1052)

🐛 Fixes

• pytest 9.1 plugin import compatibility (#1052) — libtmux's bundled pytest plugin aborted at import under pytest 9.1, breaking test collection for any project that loads tmuxp's or libtmux's fixtures. Fixed by the libtmux 0.58.1 floor bump.

📋 What's Changed

• Require libtmux 0.58.1 for the pytest 9.1 fix by @tony in https://github.com/tmux-python/tmuxp/pull/1052
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.70.0...v1.70.1

📦 libtmux 0.58.0

• libtmux 0.58.0 forces UTF-8 encoding in `subprocess.Popen`, eliminating the locale dependency. See the [libtmux 0.58.0 release](https://github.com/tmux-python/libtmux/releases/tag/v0.58.0).

📋 What's Changed

• py(deps): Test against libtmux utf-8-encoding branch by @tony in https://github.com/tmux-python/tmuxp/pull/1045
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.69.0...v1.70.0

📦 libtmux 0.57.1

• Highlights from libtmux [0.57.0](https://github.com/tmux-python/libtmux/releases/tag/v0.57.0) / [0.57.1](https://github.com/tmux-python/libtmux/releases/tag/v0.57.1):
• `Client` object and `Server.clients` accessor — typed dataclass for tmux's attached-client model
• `search_*()` methods with tmux-native `filter=` kwarg (`-f` flag) on Server, Session, and Window
• `Server.display_message` and `Window.display_message` — read tmux format tokens without a pane handle
• More format-token fields on Pane, Window, Session, and Client (zoomed, dead, marked, synchronized, path, pipe, flags, termtype, readonly)
• `LibTmuxException.subcommand` — errors now record which tmux subcommand failed
• `Pane.reset()` fix — scrollback clear works again (was silently no-op in 0.56.0)

📋 What's Changed

• Bump libtmux 0.56.0 -> 0.57.1 by @tony in https://github.com/tmux-python/tmuxp/pull/1043
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.68.0...v1.69.0

📦 Pull requests

• docs(style): refine typography, headings, TOC, and body by @tony in https://github.com/tmux-python/tmuxp/pull/1021
• docs: self-host fonts, eliminate layout shift, add SPA navigation by @tony in https://github.com/tmux-python/tmuxp/pull/1022
• test(docs[sphinx_fonts]): add tests for sphinx_fonts extension by @tony in https://github.com/tmux-python/tmuxp/pull/1023
• docs(style[shell]): standardize shell code blocks by @tony in https://github.com/tmux-python/tmuxp/pull/1024
• docs(redesign): restructure documentation to CLI Frontend Skeleton pattern by @tony in https://github.com/tmux-python/tmuxp/pull/1029
• docs(sphinx_fonts): add multi-subset support, Mono weights, and latin-ext by @tony in https://github.com/tmux-python/tmuxp/pull/1034
• docs: migrate to gp-sphinx workspace packages by @tony in https://github.com/tmux-python/tmuxp/pull/1033
• docs(feat[api-style]): improve API docs through gp-sphinx by @tony in https://github.com/tmux-python/tmuxp/pull/1035
• + 6 more

📦 Animated progress spinner for `tmuxp load`

• `tmuxp load` now shows a real-time animated spinner as windows and panes are created, replacing the static `[Loading]` message.
• Presets — five built-in display formats:
• | Preset | Description |
• |--------|-------------|
• | `default` | Spinner + progress bar + current window |
• | `minimal` | Spinner + percentage only |
• | `window` | Spinner + window name + pane index |
• | `pane` | Spinner + per-pane detail |
• + 12 more

🐛 Bug fixes

• Fix default CLI log level from INFO to WARNING so normal usage is not noisy
• Suppress raw Python tracebacks on workspace build failure; error details available via `--log-level debug` while the user sees only `[Error] <message>`
• Fix `get_pane()` to match sibling methods: widen catch to `Exception`, preserve exception chain via `from e`, replace bare `print()` with structured debug log
• Route `ls --json` and `debug-info --json` through `OutputFormatter` for consistent machine-readable output

📦 Development

• `NullHandler` per Python best practices. A new `TmuxpLoggerAdapter` provides persistent context for objects with stable identity.
• Remove `colorama` runtime and type-stub dependencies; replace with stdlib ANSI constants
• Route all raw `print()` calls through `tmuxp_echo()` for consistent output channels

📦 Links

• feat(logging): structured logging, colorama removal, OutputFormatter by @tony in https://github.com/tmux-python/tmuxp/pull/1017
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.65.0...v1.66.0

📋 What's Changed

• Bump libtmux ~=0.53.0 → ~=0.55.0 by @tony in https://github.com/tmux-python/tmuxp/pull/1019
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.64.2...v1.65.0

📦 Packaging

• Fix` __about__.__version__` not updated in 1.64.1 release
• The 1.64.1 release shipped with `__about__.__version__` still set to "1.64.0". This affected runtime version reporting (e.g. `tmuxp.__version__`).
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.64.1...v1.64.2

🐛 Bug fix

• fix(workspace/builder): Wait for shell prompt before layout and commands by @tony in https://github.com/tmux-python/tmuxp/pull/1018

📝 Documentation

• feat(docs): Add linkable arguments with headerlinks to argparse directive by @tony in https://github.com/tmux-python/tmuxp/pull/1010
• feat(docs): Render argparse metadata as semantic definition list by @tony in https://github.com/tmux-python/tmuxp/pull/1011
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.64.0...v1.64.1

📝 Custom CLI Documentation Engine

• Replaced the external `sphinx-argparse` dependency with a custom `sphinx_argparse_neo` package, providing:
• Syntax highlighting for CLI usage blocks and argparse help output
• Automatic TOC entries for command examples
• Consistent styling matching shell code blocks
• Better maintainability with comprehensive test coverage (313 tests)

📦 Before & After

• The CLI documentation now features semantic syntax highlighting:
• | Element | Color | Example |
• |---------|-------|---------|
• | `usage:` keyword | Blue | `usage: tmuxp load` |
• | Program/command | Purple | `tmuxp`, `load` |
• | Options | Teal | `--detached`, `-d` |
• | Metavars | Yellow | `SESSION`, `CONFIG` |
• | Choices | Green | `yaml`, `json` |

📝 Documentation

• Custom argparse documentation engine with syntax highlighting
• Restructured CLI command pages for consistency
• Usage blocks now match shell example styling (background, padding, border-radius)

🐛 Bug Fixes

• Fixed docutils node.children assignment bypassing parent tracking
• Added ID prefix to prevent duplicate section IDs across subcommand pages
• Escape asterisks in glob patterns to prevent RST emphasis warnings
• Fixed mypy type annotation errors

📦 Dependencies

• Removed `sphinx-argparse` external dependency
• Pinned `sphinx<9` for compatibility

📦 Links

• Documentation: https://tmuxp.git-pull.com/cli/
• PR: https://github.com/tmux-python/tmuxp/pull/1009

📦 Contributors

• @tony
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.63.1...v1.64.0

📦 CLI example colorization (#1008)

• Fix example sections not being colorized in `tmuxp --help` output
• Change `build_description` to use `"{heading} examples:"` format (e.g., "load examples:") for proper formatter detection

✨ Features

• Semantic color output for all CLI commands with a new `--color` flag (auto/always/never):
• Respects `NO_COLOR` and `FORCE_COLOR` environment variables per [no-color.org](https://no-color.org)
• All commands updated: `load`, `ls`, `freeze`, `convert`, `import`, `edit`, `shell`, `debug-info`
• Beautiful `--help` output with usage examples
• `PrivatePath` utility masks home directory as `~` for privacy
• New `tmuxp search` command for finding workspace files:
• Field-scoped search: `name:`, `session:`, `path:`, `window:`, `pane:`
• Matching options: `-i` (ignore-case), `-S` (smart-case), `-F` (fixed-strings), `-w` (word)
• + 8 more

📦 Development

• Makefile → Justfile (#1005): Migrate to `just` for development tasks

📝 Documentation

• pretty_argparse extension (#1007): Sphinx extension with CLI usage syntax highlighting, ANSI stripping, and enhanced example formatting
• Migrate docs deployment to AWS OIDC authentication
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.62.0...v1.63.0

✨ Features

• Semantic color output for all CLI commands with a new `--color` flag (auto/always/never):
• Respects `NO_COLOR` and `FORCE_COLOR` environment variables per [no-color.org](https://no-color.org)
• All commands updated: `load`, `ls`, `freeze`, `convert`, `import`, `edit`, `shell`, `debug-info`
• Beautiful `--help` output with usage examples
• `PrivatePath` utility masks home directory as `~` for privacy
• New `tmuxp search` command for finding workspace files:
• Field-scoped search: `name:`, `session:`, `path:`, `window:`, `pane:`
• Matching options: `-i` (ignore-case), `-S` (smart-case), `-F` (fixed-strings), `-w` (word)
• + 8 more

📦 Development

• Makefile → Justfile (#1005): Migrate to `just` for development tasks

📝 Documentation

• pretty_argparse extension (#1007): Sphinx extension with CLI usage syntax highlighting, ANSI stripping, and enhanced example formatting
• Migrate docs deployment to AWS OIDC authentication
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.62.0...v1.63.0a0

🐛 Fixed traceback on session load ([#1002](https://github.com/tmux-python/tmuxp/issues/1002), [#1003](https://github.com/tmux-python/tmuxp/pull/1003))

• Fixed an issue where `tmuxp load` would display a traceback after users detached from a killed session.
• After running `tmuxp load`, users would see this traceback printed to their terminal after detaching:
• ```
• Traceback (most recent call last):
• File "~/.local/bin/tmuxp", line 7, in <module>
• sys.exit(cli.cli())
• ...
• File ".../tmuxp/cli/load.py", line 152, in _load_attached
• + 16 more

📦 libtmux 0.52.1 → 0.53.0

• Breaking Change: Minimum libtmux version bumped from 0.52.1 to 0.53.0.
• libtmux 0.53.0 includes:
• Fix for `Session.attach()`: Removes the `refresh()` call that caused `TmuxObjectDoesNotExist` exceptions when sessions were killed during attachment

📦 Development Updates

• Bumped development dependencies
• Updated uv from 0.9.16 to 0.9.17

📦 Installation

• pip:
• ```bash
• pip install --upgrade tmuxp
• ```
• uv:
• ```bash
• uv add tmuxp
• ```
• + 8 more

📋 What's Changed

• py(deps) Bump libtmux 0.52.1 -> 0.53.0 by @tony in https://github.com/tmux-python/tmuxp/pull/1003
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.61.0...v1.62.0

💥 Breaking changes

• py(deps) libtmux 0.51.0 -> 0.52.1, gp-libs 0.0.17 by @tony in https://github.com/tmux-python/tmuxp/pull/1001
• Both packages are now published via [PyPI Trusted Publishers](https://docs.pypi.org/trusted-publishers/)
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.60.1...v1.61.0

📦 Deployment

• ci(release): Migrate to PyPI Trusted Publisher by @tony in https://github.com/tmux-python/tmuxp/pull/1000
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.60.0...v1.60.1

💥 Breaking changes

• py(deps) libtmux 0.50.1 -> 0.51.0 by @tony in https://github.com/tmux-python/tmuxp/pull/999
• This libtmux bump will have a hard exception raised for legacy APIs - rather than just a warning.
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.59.1...v1.60.0

📋 What's Changed

• py(deps) libtmux 0.50.0 -> 0.50.1 by @tony in https://github.com/tmux-python/tmuxp/pull/998
• Docstring fixes by @tony in https://github.com/tmux-python/tmuxp/pull/997
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.59.0...v1.59.1

💥 Breaking changes

• libtmux minimum version bumped from 0.49.0 -> 0.50.0.
• Internal updates to use libtmux's new unified options API:
• `Session.attach_session()` → `Session.attach()`
• `Window.show_window_option()` → `Window.show_option()`
• `Window.show_window_options()` → `Window.show_options()`
• `Window.set_window_option()` → `Window.set_option()`
• `g=True` parameter → `global_=True`
• Note: Options now return Python-native types (`True`/`False` instead of
• + 1 more

📋 What's Changed

• libtmux 0.49.0 -> 0.50.0 and API updates by @tony in https://github.com/tmux-python/tmuxp/pull/996
• Full Changelog:
• https://github.com/tmux-python/tmuxp/compare/v1.58.0...v1.59.0

💥 Breaking Changes

• Drop support for tmux versions < 3.2 by @tony in https://github.com/tmux-python/tmuxp/pull/993
• py(deps) libtmux 0.48.0 -> 0.49.0 by @tony in https://github.com/tmux-python/tmuxp/pull/992
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.57.0...v1.58.0

💥 Breaking changes

• Deprecate tmux versions below 3.2a by @tony in https://github.com/tmux-python/tmuxp/pull/991
• py(deps) libtmux 0.47.0 -> 0.48.0 by @tony in https://github.com/tmux-python/tmuxp/pull/990

📦 Development

• tmux: Add tmux 3.6 to testgrid by @tony in https://github.com/tmux-python/tmuxp/pull/989
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.56.0...v1.57.0

💥 Breaking changes

• Drop Python 3.9 by @tony in https://github.com/tmux-python/tmuxp/pull/987
• Minimum libtmux version to v0.47.0

📦 Development

• Support Python 3.14 by @tony in https://github.com/tmux-python/tmuxp/pull/986

📋 What's Changed

• docs(README): fix removed $ sign in the ins by @isandesh7 in https://github.com/tmux-python/tmuxp/pull/976

✨ New Contributors

• @isandesh7 made their first contribution in https://github.com/tmux-python/tmuxp/pull/976
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.55.0...v1.56.0

📋 What's Changed

• py(deps) libtmux 0.45.0 -> 0.46.0 by @tony in https://github.com/tmux-python/tmuxp/pull/969
• Update for `libtmux.test` imports.
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.54.0...v1.55.0

💥 Breaking changes

• py(deps) libtmux 0.44.2 -> 0.45.0 by @tony in https://github.com/tmux-python/tmuxp/pull/968
• Update for `libtmux.test` imports.

📦 CI

• ci(tests) Verify runtime deps for CLI commands by @tony in https://github.com/tmux-python/tmuxp/pull/967
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.53.0...v1.54.0

📝 Docs

• Doc improvements by @tony in https://github.com/tmux-python/tmuxp/pull/963

📦 Packaging

• py(deps) libtmux 0.42.0 -> 0.44.2 by @tony in https://github.com/tmux-python/tmuxp/pull/962

🧪 Test overhaul

• Tests: Improved parametrization by @tony in https://github.com/tmux-python/tmuxp/pull/964
• ci(tests) Verify runtime deps by @tony in https://github.com/tmux-python/tmuxp/pull/965
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.52.2...v1.53.0

📦 Compatibility

• `run_before_script`: Fix output capturing too many newlines by @tony in https://github.com/tmux-python/tmuxp/pull/960
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.52.1...v1.52.2

🐛 Bug fixes

• Fix `run_before_script()` output capturing by @tony in https://github.com/tmux-python/tmuxp/pull/959
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.52.0...v1.52.1

📋 What's Changed

• py(deps) libtmux 0.40.1 -> 0.42.0, modernized `run_before_script()` by @tony in https://github.com/tmux-python/tmuxp/pull/958
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.51.0...v1.52.0

📦 Development

• Use future annotations by @tony in https://github.com/tmux-python/tmuxp/pull/957
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.50.1...v1.51.0

📦 libtmux update

• py(deps) libtmux: 0.40.0 -> 0.40.1 by @tony in https://github.com/tmux-python/tmuxp/pull/956
• Bug fix for server environmental variables from https://github.com/tmux-python/libtmux/pull/553.
• Thank you @ppentchev!
• Full Changelog: https://github.com/tmux-python/tmuxp/compare/v1.50.0...v1.50.1