Use when the user asks to "update libtmux", "bump libtmux", "upgrade libtmux dependency", "check for new libtmux version", or when investigating whether tmuxp needs a libtmux update. Guides the full workflow: studying upstream changes, updating the dependency, migrating code and tests, and producing separate atomic commits with rich messages.
Workflow for updating the libtmux dependency in tmuxp with separate, atomic commits.
This skill produces up to four atomic commits on a dedicated branch, then opens a PR:
pyproject.toml + uv.lockEach commit stands alone, passes tests independently, and has a rich commit body.
Gather current state before making any changes.
Read pyproject.toml and find the libtmux~=X.Y.Z specifier in .
[project] dependenciespip index versions libtmux
If the user provided a target version, use that. Otherwise use the latest from PyPI.
If the current specifier already covers the target version, inform the user and stop.
The local libtmux clone lives at ~/work/python/libtmux. Fetch and check:
cd ~/work/python/libtmux && git fetch --tags && git log --oneline -5
Verify the target version tag exists. If not, the version may not be released yet — warn the user.
This is the most important step. Read the libtmux CHANGES file to understand what changed between the current pinned version and the target.
Read ~/work/python/libtmux/CHANGES from the section for the target version back through all versions since the current pin.
Categorize changes into:
| Category | Action needed in tmuxp |
|---|---|
| Breaking changes | Must fix code/tests |
| Deprecations | Should migrate away |
| New APIs | Optionally adopt |
| Bug fixes | Note for commit message |
| Internal/docs | Note for commit message only |
For each breaking change or deprecation, grep tmuxp source and tests:
# Example: if Window.rename_window() changed signature
rg "rename_window" src/ tests/
Search patterns to check (adapt based on actual changes):
For breaking changes where the CHANGES entry is unclear, read the actual commits:
cd ~/work/python/libtmux && git log --oneline v{CURRENT}..v{TARGET} -- src/
Present findings to the user before proceeding:
Get user confirmation to proceed.
git checkout -b deps/libtmux-{TARGET_VERSION}
Branch naming convention: deps/libtmux-X.Y.Z
Update the dependency specifier and lock file.
Change the libtmux~=X.Y.Z line in [project] dependencies.
uv lock
uv sync
uv run py.test tests/ -x -q 2>&1 | tail -20
Note any failures — these indicate code changes needed in Step 4.
Commit message format (use heredoc for multiline):
deps(libtmux[~=X.Y.Z]): Bump from ~=A.B.C