v0.50.0 - options and hook management

libtmux 0.50 brings a major enhancement to option and hook management with a unified, typed API for managing tmux options and hooks across all object types.

Highlights

• Unified Options API: New show_option(), show_options(), set_option(), and unset_option() methods available on Server, Session, Window, and Pane
• Hook Management: Full programmatic control over tmux hooks with support for indexed hook arrays and bulk operations
• SparseArray: New internal data structure for handling tmux's sparse indexed arrays (e.g., command-alias[0], command-alias[99])
• tmux 3.2+ baseline: Removed support for tmux versions below 3.2a, enabling cleaner code and full hook/option feature support

Unified Options API

All tmux objects now share a consistent options interface:

import libtmux

server = libtmux.Server()
session = server.sessions[0]
window = session.windows[0]

# Get all options as a structured dict
session.show_options()
# {'activity-action': 'other', 'base-index': 0, ...}

# Get a single option value
session.show_option('base-index')
# 0

# Set an option
window.set_option('automatic-rename', True)

# Unset an option (revert to default)
window.unset_option('automatic-rename')

Hook Management

Programmatic control over tmux hooks:

session = server.sessions[0]

# Set a hook
session.set_hook('session-renamed', 'display-message "Renamed!"')

# Get hook value (returns SparseArray for indexed hooks)
session.show_hook('session-renamed')
# {0: 'display-message "Renamed!"'}

# Get all hooks
session.show_hooks()

# Remove a hook
session.unset_hook('session-renamed')

# Bulk operations for indexed hooks
session.set_hooks('session-renamed', {
    0: 'display-message "Hook 0"',
    1: 'display-message "Hook 1"',
    5: 'run-shell "echo hook 5"',
})

Breaking Changes

Deprecated Window methods

The following methods are deprecated and will be removed in a future release:

Deprecated	Replacement
Window.set_window_option()	Window.set_option()
Window.show_window_option()	Window.show_option()
Window.show_window_options()	Window.show_options()

Deprecated g parameter

The g parameter for global options is deprecated in favor of global_:

# Before (deprecated)
session.show_option('status', g=True)

# After (0.50.0+)
session.show_option('status', global_=True)

New Constants

• OptionScope enum: Server, Session, Window, Pane
• OPTION_SCOPE_FLAG_MAP: Maps scope to tmux flags (-s, -w, -p)
• HOOK_SCOPE_FLAG_MAP: Maps scope to hook flags

Documentation

• New topic guide: Options and Hooks
• New topic guides: Automation patterns, Workspace setup, Pane interaction, QueryList filtering
• Refreshed README with hero section, quickstart, and more examples

tmux Version Compatibility

Feature	Minimum tmux
All options/hooks features	3.2+
Window/Pane hook scopes (-w, -p)	3.2+
client-active, window-resized hooks	3.3+
pane-title-changed hook	3.5+

What's Changed

• Improved option management, add hook management by @tony in #516
• Refresh README by @tony in #609

Full Changelog: v0.49.0...v0.50.0

v0.49.0 (drop tmux < 3.2)

What's Changed

Breaking: tmux <3.2 fully dropped

• Drop support for tmux versions < 3.2 by @tony in #608

Full Changelog: v0.48.0...v0.49.0

v0.48.0 (deprecating tmux <3.2)

What's Changed

Breaking: tmux <3.2 deprecated

Deprecate old tmux versions by @tony in #606

Development

tmux: Add tmux 3.6 to testgrid by @tony in #607

Full Changelog: v0.47.0...v0.48.0

v0.47.0 - Drop Python 3.9

Breaking changes

• Support Python 3.14 by @tony in #601
• Drop Python 3.9 by @tony in #602

Full Changelog: v0.46.2...v0.47.0

v0.46.2 - `start_directory` typing fix

What's Changed

• Fix new_window argument typing in Session by @Data5tream in #596
  • types: Add StrPath typing, fix new_session by @tony in #597
    • types: Add StrPath typing, fix new_session, part 2 by @tony in #598

New Contributors

• @Data5tream made their first contribution in #596

Full Changelog: v0.46.1...v0.46.2

v0.46.1 - Maintenance release

Full Changelog: v0.46.0...v0.46.1

Changes

Feature branch at v0.46.x

v0.46.x will extend the life of v0.46.0 while new features are being developed for watching for changes within libtmux panes, windows, and sessions.

See:

• #587
• #582

Documentation

• Fix typo in Pane.send_keys (#593)

  Thank you @subbyte!

v0.46.0 - Internal improvements

Breaking Changes

• Test Helper Imports Refactored: Direct imports from libtmux.test are no longer possible. You must now import from specific submodules (#580)

  # Before:
  from libtmux.test import namer
  # After: 
  from libtmux.test.named import namer

  # Before:
  from libtmux.test import RETRY_INTERVAL_SECONDS
  # After: 
  from libtmux.test.constants import RETRY_INTERVAL_SECONDS

Internal Improvements

• Enhanced Test Utilities: The EnvironmentVarGuard now handles variable cleanup more reliably
• Comprehensive Test Coverage: Added test suites for constants and environment utilities
• Code Quality: Added proper coverage markers to exclude type checking blocks from coverage reports
• Documentation: Improved docstrings and examples in the random module

These changes improve maintainability of test helpers both internally and for downstream packages that depend on libtmux.

What's Changed

• Coverage: Test helpers by @tony in #580

Full Changelog: v0.45.0...v0.46.0

v0.45.0 - test helpers overhaul

What's Changed

Breaking Changes

Test helpers: Refactor

by @tony in #578

Test helper functionality has been split into focused modules (#578):

• libtmux.test module split into:
  • libtmux.test.constants: Test-related constants (TEST_SESSION_PREFIX, etc.)
  • libtmux.test.environment: Environment variable mocking
  • libtmux.test.random: Random string generation utilities
  • libtmux.test.temporary: Temporary session/window management

Breaking: Import paths have changed. Update imports:

# Old (0.44.x and earlier)
from libtmux.test import (
    TEST_SESSION_PREFIX,
    get_test_session_name,
    get_test_window_name,
    namer,
    temp_session,
    temp_window,
    EnvironmentVarGuard,
)

# New (0.45.0+)
from libtmux.test.constants import TEST_SESSION_PREFIX
from libtmux.test.environment import EnvironmentVarGuard
from libtmux.test.random import get_test_session_name, get_test_window_name, namer
from libtmux.test.temporary import temp_session, temp_window

Misc

• Cursor rules: Add Cursor Rules for Development and Git Commit Standards by @tony in #575

CI

• tests(ci) Check runtime deps import correctly by @tony in #574

Full Changelog: v0.44.2...v0.45.0

v0.44.2 - Bug fix, doc and test tweaks

What's Changed

Bug fixes

• fix(typings) Move typing-extensions into TypeGuard by @tony in #572

Documentation

• Doc / typos fixes by @tony in #569

Development

• Tests: Improved parametrization by @tony in #570

Full Changelog: v0.44.1...v0.44.2

v0.44.1 - Maintenance release

What's Changed

Packaging

• types: Only use typing-extensions if necessary by @ppentchev in #563

Full Changelog: v0.44.0...v0.44.1