Bug fixes

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

What's Changed

Features

CLI Colors (#1006)

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
• 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

Search Command (#1006)

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)
• Logic operators: --any for OR, -v for invert match
• Output formats: human (with match highlighting), --json, --ndjson

Enhanced ls Command (#1006)

• --tree: Display workspaces grouped by directory
• --full: Include complete parsed config content
• --json / --ndjson: Machine-readable output for jq pipelines
• Local workspace discovery from current directory and parents
• "Global workspace directories" section shows XDG vs legacy paths

JSON Output for debug-info (#1006)

• tmuxp debug-info --json: Structured output for automation and issue reporting

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: v1.62.0...v1.63.0

What's Changed

Features

CLI Colors (#1006)

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
• 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

Search Command (#1006)

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)
• Logic operators: --any for OR, -v for invert match
• Output formats: human (with match highlighting), --json, --ndjson

Enhanced ls Command (#1006)

• --tree: Display workspaces grouped by directory
• --full: Include complete parsed config content
• --json / --ndjson: Machine-readable output for jq pipelines
• Local workspace discovery from current directory and parents
• "Global workspace directories" section shows XDG vs legacy paths

JSON Output for debug-info (#1006)

• tmuxp debug-info --json: Structured output for automation and issue reporting

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: v1.62.0...v1.63.0a0

Highlights

This release fixes an important bug where users would see a TmuxObjectDoesNotExist traceback after detaching from a session that was killed during use. The fix comes via the libtmux 0.53.0 dependency update.

Bug Fixes

Fixed traceback on session load (#1002, #1003)

Fixed an issue where tmuxp load would display a traceback after users detached from a killed session.

The Problem

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
    builder.session.attach()
  File ".../libtmux/session.py", line 332, in attach
    self.refresh()
  File ".../libtmux/neo.py", line 242, in fetch_obj
    raise exc.TmuxObjectDoesNotExist(...)
libtmux.exc.TmuxObjectDoesNotExist: Could not find object

When It Occurred

Users encountered this when they:

1. Loaded a tmux session via tmuxp load
2. Worked in the session
3. Killed the session (e.g., closed all windows) before detaching
4. Detached from tmux

Root Cause

The issue was in libtmux's Session.attach() method, which called refresh() after the attach-session command returned. Since attach-session is a blocking interactive command, the session state can change arbitrarily during attachment — including being killed entirely. Attempting to refresh a non-existent session caused the exception.

Timeline

• Feb 2024: libtmux added Session.attach() with the refresh() call
• Nov 2025: tmuxp switched from the older attach_session() to attach()
• Users started experiencing the bug

Resolution

Fixed in libtmux 0.53.0 (libtmux#616) by removing the unnecessary refresh() call from Session.attach().

Dependency Updates

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:

pip install --upgrade tmuxp

uv:

uv add tmuxp

uvx (one-time use):

uvx tmuxp load <config>

pipx:

pipx upgrade tmuxp

What's Changed

• py(deps) Bump libtmux 0.52.1 -> 0.53.0 by @tony in #1003

Full Changelog: 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 #1001

  Both packages are now published via PyPI Trusted Publishers

Full Changelog: v1.60.1...v1.61.0

Deployment

• ci(release): Migrate to PyPI Trusted Publisher by @tony in #1000

Full Changelog: v1.60.0...v1.60.1

Breaking changes

• py(deps) libtmux 0.50.1 -> 0.51.0 by @tony in #999

  This libtmux bump will have a hard exception raised for legacy APIs - rather than just a warning.

Full Changelog: v1.59.1...v1.60.0

What's Changed

• py(deps) libtmux 0.50.0 -> 0.50.1 by @tony in #998
• Docstring fixes by @tony in #997

Full Changelog: v1.59.0...v1.59.1

Breaking changes

libtmux 0.50.0 (#996)

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
"on"/"off", int instead of numeric strings).

What's Changed

• libtmux 0.49.0 -> 0.50.0 and API updates by @tony in #996

Full Changelog:
v1.58.0...v1.59.0

Breaking Changes

• Drop support for tmux versions < 3.2 by @tony in #993
• py(deps) libtmux 0.48.0 -> 0.49.0 by @tony in #992

Full Changelog: v1.57.0...v1.58.0