What's Changed

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:

New CLI flags:

• --progress-format <preset-or-custom> — select a preset or pass a custom format string with tokens like {bar}, {progress}, {window}, {pane_index}, {overall_percent}
• --progress-lines N — number of before_script output lines shown in the spinner panel (default: 3)
• --no-progress — disable the spinner entirely

Environment variables:

• TMUXP_PROGRESS=0 — disable spinner (same as --no-progress)
• TMUXP_PROGRESS_FORMAT — default preset/format string
• TMUXP_PROGRESS_LINES — default panel line count

The spinner stops cleanly before interactive prompts (session switch, error recovery) and before tmux attach. Non-TTY environments automatically fall back to the original behavior.

• feat(load): animated progress spinner for tmuxp load by @tony in #1020

Full Changelog: v1.66.0...v1.67.0

What's Changed

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

Structured logging with extra context across all modules

All modules now use logging.getLogger(__name__) with structured extra keys (tmux_session, tmux_window, tmux_pane, tmux_config_path, etc.) for filtering and aggregation. Library __init__.py adds
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 #1017

Full Changelog: v1.65.0...v1.66.0

Maintenance only, no bugfixes or new features

What's Changed

• Bump libtmux ~=0.53.0 → ~=0.55.0 by @tony in #1019

Full Changelog: v1.64.2...v1.65.0

What's changed

No code changes.

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: v1.64.1...v1.64.2

What's Changed

Bug fix

• fix(workspace/builder): Wait for shell prompt before layout and commands by @tony in #1018

Documentation

• feat(docs): Add linkable arguments with headerlinks to argparse directive by @tony in #1010
• feat(docs): Render argparse metadata as semantic definition list by @tony in #1011

Full Changelog: v1.64.0...v1.64.1

This release brings a major overhaul to CLI documentation with a custom argparse documentation engine featuring syntax highlighting.

Highlights

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:

What's Changed

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: #1009

Contributors

• @tony

Full Changelog: v1.63.1...v1.64.0

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