v1.68.0 - Improved docs, libtmux bump

What's Changed

tmuxp 1.68.0 refreshes the documentation stack and developer workflow for the next release train. The docs now sit on the shared gp-sphinx platform, the API pages pick up the newer gp-furo visual language, and the test suite avoids paying for each contributor's interactive shell startup. The release also raises the libtmux floor so tmuxp shell users can script against the expanded tmux command wrapper surface.

Documentation platform refresh

tmuxp's docs were reshaped around a CLI-first frontend: a standalone homepage, clearer install and YAML examples, a stronger CLI reference, new exit-code and recipe pages, topic/project sections, redirects for moved pages, and the Python API moved under internals with clearer expectations for end users. See the 1.68.0 documentation notes.

The site now inherits shared gp-sphinx infrastructure instead of carrying repo-local Sphinx extension copies: Furo-based theme defaults, IBM Plex typography, packaged argparse documentation helpers, API badge styling, MyST-aware object references, and the sphinx-vite-builder asset pipeline. That keeps tmuxp aligned with the surrounding tmux-python docs while reducing custom docs plumbing in this repo.

Shell examples were standardized to one console command per block with $ prompts and continuation lines for long commands, so commands are easier to read and copy from the rendered docs. See the command-block notes.

libtmux 0.56.0

tmuxp now requires libtmux~=0.56.0, picking up libtmux 0.55.1's test-socket cleanup and libtmux 0.56.0's broad command-coverage release. tmuxp's runtime imports stay on stable APIs, while tmuxp shell users can reach more upstream wrappers for interactive tmux commands, buffer I/O, key bindings, shell execution, and window/pane manipulation without falling back to raw cmd() calls. See the dependency notes and the libtmux 0.56.0 release.

Faster local tests

The pytest suite now pins $SHELL=/bin/sh while tests run, so tmux panes created by fixtures skip zsh/bash profile startup and other local interactive shell work. On the measured local suite this reduced uv run py.test wall time from about 76 seconds to about 36 seconds, with no tmuxp runtime behavior change. See the development notes.

Release-note cleanup

CHANGES was rewritten end to end in the new release-note style, preserving the full tmuxp history while making old and current entries easier to scan from the rendered history page.

Pull requests

• docs(style): refine typography, headings, TOC, and body by @tony in #1021
• docs: self-host fonts, eliminate layout shift, add SPA navigation by @tony in #1022
• test(docs[sphinx_fonts]): add tests for sphinx_fonts extension by @tony in #1023
• docs(style[shell]): standardize shell code blocks by @tony in #1024
• docs(redesign): restructure documentation to CLI Frontend Skeleton pattern by @tony in #1029
• docs(sphinx_fonts): add multi-subset support, Mono weights, and latin-ext by @tony in #1034
• docs: migrate to gp-sphinx workspace packages by @tony in #1033
• docs(feat[api-style]): improve API docs through gp-sphinx by @tony in #1035
• chore(docs): adopt gp-sphinx v0.0.1a8 by @tony in #1036
• chore(docs): bump gp-sphinx to 0.0.1a16 for sphinx-vite-builder consolidation by @tony in #1037
• py(deps): bump libtmux to 0.56.0 by @tony in #1038
• tests(perf[conftest]): pin $SHELL=/bin/sh for a faster suite by @tony in #1041
• docs(CHANGES): rewrite release history for May 2026 refresh by @tony in #1042

Full Changelog: v1.67.0...v1.68.0

v1.67.0 - `tmuxp load` progress spinner

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:

Preset	Description
default	Spinner + progress bar + current window
minimal	Spinner + percentage only
window	Spinner + window name + pane index
pane	Spinner + per-pane detail
verbose	Spinner + bar + window + pane + percentage

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

v1.66.0 - logging improvements

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

v1.65.0 - Maintenance release

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

v1.64.2 - Packaging hotfix

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

v1.64.1 - Fix shell artifact on load for ZSH systems

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

v1.64.0

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:

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

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

tmuxp v1.63.1

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

v1.63.0 - CLI Colors

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

tmuxp v1.63.0a0

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