tmuxp 1.74.0 pairs a libtmux upgrade with a documentation overhaul. It bumps libtmux to 0.61.0 — hardening tmux 3.7 patch-line support — and teaches tmuxp debug-info to report the exact tmux patch release (3.7a/3.7b) instead of the numeric-normalized version. The docs also gain theme-aware inline diagrams and a concept-first rewrite that leads with what each feature is before its configuration.

Highlights

libtmux 0.61.0

The libtmux floor moves from ~=0.60.0 to ~=0.61.0, hardening tmux 3.7 patch-line support. libtmux's Pane.break_pane() now keeps tmux's own default window name on tmux 3.7a/3.7b instead of forcing libtmux, and a new get_version_str() helper exposes the raw tmux version string. tmux 3.2a–3.6 are unaffected.

tmuxp debug-info reports the exact tmux patch release

tmuxp debug-info now shows tmux's full version, keeping the point-release letter (for example 3.7a) that was previously normalized away to 3.7. Because tmux patch releases can differ in behavior, the precise release is what a bug report needs.

Themed diagrams across the docs

Diagrams now render as theme-aware inline graphics that follow the site's light/dark palette and code styling, replacing the old static ASCII art. The workspace-builders guide gains a load → build → attach flow diagram, and the examples page shows each pane example as a faithful tmux window layout.

Concept-first documentation pass

The docs now open with what each feature is before its configuration, in a consistent second-person voice, with advanced and Python-only material marked opt-in. New diagrams trace the plugin hook lifecycle, the CLI request flow, the workspace hierarchy, and what tmuxp load does inside an existing session.

Development

The build-time mermaid diagram renderer, previously bundled with the docs, now comes from the reusable sphinx-gp-mermaid package. Rendered output is unchanged.

What's Changed

• Docs: build-time mermaid + tmux-layout diagram rendering by @tony in #1071
• docs: voice-guide compliance pass, diagrams, and fixes by @tony in #1072
• Docs: consume sphinx-gp-mermaid, drop the vendored renderer by @tony in #1073
• libtmux 0.61.0 by @tony in #1074

Full Changelog: v1.73.0...v1.74.

What's new

Pluggable workspace builders (#1066)

tmuxp can now build a workspace with a builder other than its built-in one. Point a workspace file's workspace_builder key at an installed builder — by registered name or by Python import path — and tmuxp loads the session through it. Builders that ship outside tmuxp's environment can be imported from directories listed in workspace_builder_paths, which tmuxp trusts only for that load. The built-in builder stays the default, so existing workspaces are unaffected.

Configurable pane readiness (#1066)

Before sending a pane's layout and commands, tmuxp can wait for the shell to draw its prompt — a guard against a zsh prompt-redraw artifact. That wait is now a policy you set per workspace:

workspace_builder_options:
  pane_readiness: auto   # auto | always | never (also true/false)

The new default, auto, waits only when the session's shell is zsh, so zsh users see no change while bash, sh, and other shells skip a wait they never needed. Set always to keep the previous wait-everywhere behavior, or never to skip it entirely.

Workspace builder API (#1066)

tmuxp.workspace.builder is now a package. The default builder is ClassicWorkspaceBuilder, with WorkspaceBuilder kept as a backwards-compatible alias. Third-party builders implement WorkspaceBuilderProtocol (shaped to allow async builders later) and are resolved by resolve_builder_class() from an entry point or import path, with trusted import directories handled by resolve_builder_paths(). Builder behavior is configured through WorkspaceBuilderOptions and PaneReadiness, and resolution failures raise WorkspaceBuilderError and its subclasses.

See the custom workspace builders guide for details.

What's Changed

• Pluggable workspace builders and configurable pane readiness by @tony in #1066

Full Changelog: v1.72.0...v1.73.0

What's new

tmux 3.7 compatibility (#1065)

libtmux 0.60.0 completes tmux 3.7 feature parity at the library layer tmuxp builds on: floating panes (Window.new_pane() / Pane.new_pane()), typed tmux 3.7 server, session, window, and pane options, new pane format variables, and new tmux 3.7 command flags. Every 3.7-only surface is version-gated, so tmux 3.2a-3.6 are unaffected. These APIs are reachable through tmuxp's Python API and tmuxp shell; the YAML workspace format is unchanged.

Dependencies

• Minimum libtmux~=0.60.0 (was ~=0.59.0) — libtmux 0.60.0 completes tmux 3.7 feature parity. (#1065)

What's Changed

• py(deps[libtmux]) Bump 0.59.0 -> 0.60.0 (tmux 3.7 feature parity) by @tony in #1065

Full Changelog: v1.71.0...v1.72.0

What's new

tmux 3.7 support (#1057)

tmuxp now supports tmux 3.7, which joins 3.2a through 3.6 in the tested version range. There are no behavior changes for users on earlier tmux releases.

Dependencies

• Minimum libtmux~=0.59.0 (was ~=0.58.1) — libtmux 0.59.0 adds tmux 3.7 support. (#1057)

What's Changed

• py(deps[libtmux]) Bump 0.58.1 -> 0.59.0 (tmux 3.7 support) by @tony in #1057

Full Changelog: v1.70.1...v1.71.0

tmuxp 1.70.1 bumps libtmux to 0.58.1, fixing a pytest 9.1 plugin import failure that broke test collection for projects using tmuxp's or libtmux's fixtures.

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 #1052

Full Changelog: v1.70.0...v1.70.1

tmuxp 1.70.0 bumps libtmux to 0.58.0, fixing session and window listing on systems whose locale is not UTF-8.

Full release notes: https://tmuxp.git-pull.com/history/#tmuxp-1-70-0-2026-05-23

libtmux 0.58.0

libtmux's subprocess output decoding previously relied on the system locale. On non-UTF-8 locales, the format-separator byte sequence could be corrupted, causing tmuxp's session and window listing to silently return empty results.

libtmux 0.58.0 forces UTF-8 encoding in subprocess.Popen, eliminating the locale dependency. See the libtmux 0.58.0 release.

What's Changed

• py(deps): Test against libtmux utf-8-encoding branch by @tony in #1045

Full Changelog: v1.69.0...v1.70.0

tmuxp 1.69.0 raises the libtmux floor to 0.57.1, bringing client-awareness, tmux-native filtering, and expanded format-token fields to tmuxp shell users.

Full release notes: https://tmuxp.git-pull.com/history/#tmuxp-1-69-0-2026-05-23

libtmux 0.57.1

The libtmux bump pulls in the 0.57.x command-coverage and client-awareness releases. Scripts launched through tmuxp shell can now work with attached-client objects and use tmux-native filtering to query sessions, windows, and panes without manual post-filtering.

Highlights from libtmux 0.57.0 / 0.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 #1043

Full Changelog: v1.68.0...v1.69.0

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

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