Repository navigation
Description
Summary
.github/SCRIPTS.md now sets the rules for support scripts. Against it, libtmux-java has 3 items to delete as parity with Python libtmux or tmuxp, 1 to delete for having no caller, 5 to move under scripts/<name>/ with typed Python and tests, 4 to consolidate into shared tooling, 1 to remove once the API lands, and 2 to keep. The Clojure modules add three Gradle-driven .clj runners, which stay.
Motivation
.github/SCRIPTS.md keeps a script only for a current use (a CI job, a release step, a generator, a docs check or a maintainer task in CONTRIBUTING.md), says parity with Python libtmux or tmuxp is not a use, and requires kept scripts to live in scripts/<name>/ with a README and tests and to pass ruff format, ruff check, ty check and pytest in CI. The decision is in libtmux/docs#323. A scan of trunk found the items below.
Tasks
Delete: parity with Python libtmux or tmuxp
- The
import libtmuxassertion in the step "Install the optional workspace Python test runtime":.github/workflows/ci.ymlL87-L89 and.github/workflows/tmux-matrix.ymlL242-L244. It asserts that Python libtmux'sTMUX_MIN_VERSIONis3.3a, which checks parity between the two floors and tests no behavior of this port. - The rest of that step, which appears in
.github/workflows/ci.ymlL78-L91 and.github/workflows/tmux-matrix.ymlL233-L246: thetmuxp==1.74.0venv, thetmux-python/libtmuxfetch at one commit and thePYTHONPATHexport. SCRIPTS.md lists installs of tmuxp and clones of Python libtmux for deletion. The shippedworkspace-clibridge runs Python tmuxp 1.74.0 and refuses a Python libtmux without optional-feature policy v2, which no release has (libtmux-workspace-cli/src/main/java/io/github/libtmux/workspace/cli/PythonExtensions.javaL23-L34), so the fetch supplies a commit that has it. The bridge fixtures callassumeTrueonTMUX_WORKSPACE_TEST_PYTHON(libtmux-workspace-cli/src/test/java/io/github/libtmux/workspace/cli/ExecutionTest.javaL285-L287) and skip without it. Decide whether the bridge and its tests go with the step, or SCRIPTS.md records an exception for it, before removing it.- Left open: the
workspace-cliPython bridge needs this step until Decide whether the workspace CLIs keep their tmuxp and Python libtmux bridge docs#324 decides what happens to the bridge. The floor assertion is gone.
- Left open: the
- The parity ledgers
docs/parity/python-api.mdanddocs/parity/test-map.md, thePARITYchecks over them indocs/src/test/java/io/github/libtmux/docs/DocumentationFactsTest.javaL64, and the entries indocs/README.mdL105-L110 anddocs/README.mdL315-L316.
Delete: no caller
-
tools/ci/tmux_ref.pyandtools/ci/test_tmux_ref.py: nothing calls the module. The workflows build tmux with.github/scripts/tmux_build.py(.github/workflows/tmux-matrix.ymlL133,.github/workflows/tmux-matrix.ymlL147) and CONTRIBUTING names that script as the builder (.github/CONTRIBUTING.mdL316).tmux-matrix.ymlstill liststools.ci.test_tmux_refin its unittest run (.github/workflows/tmux-matrix.ymlL76), so CI tests dead code. Drop it from that list. The swift port carries a near-identical copy (Scripts/tmux_ref.py).
Move to scripts/<name>/ with typed Python and tests
-
tools/ci/check.pywithtools/ci/test_check.py: checks the docs and workflows against the tmux lanes (.github/workflows/tmux-matrix.ymlL78). -
tools/verify-staged-release.shwithtools/ci/test_staged_release.py: checks a staged release against what the Central Portal refuses (.github/workflows/ci.ymlL167,.github/workflows/tmux-matrix.ymlL77). Port the shell to Python. -
tools/tmux-matrix.sh(.github/CONTRIBUTING.mdL146) andtools/reap-stale-servers.sh(.github/CONTRIBUTING.mdL129): maintainer tasks written in shell.docs/decisions/0006-real-tmux-junit5-fixture-lifecycle.mdL76 names the reaper asscripts/reap-stale-servers.sh; fix the path when it moves. -
gradle/test-fixtures/io/github/libtmux/fixtures/pty.py: PTY helper that the Java tests read as a resource (libtmux-workspace-cli/src/test/java/io/github/libtmux/workspace/cli/ProcessTest.javaL34,integration-tests/src/test/java/io/github/libtmux/it/NativeClient.javaL153). It needs the same format, lint and type checks. - CI checks: the repository has no
ruffortyconfiguration or CI step..github/workflows/tmux-matrix.ymlL76-L78 runsunittestand.github/workflows/tmux-matrix.ymlL162-L165 installspytestinto a venv. Addruff format --check,ruff check,ty checkandpytestwithpytest-asyncioand doctests overscripts/.
Consolidate into shared tooling
-
tools/apt-get.sh: git blob6f1fa72f50f38a8e63de3e78b3e9a3bcfa4b2004, identical in the cxx, dotnet, java and swift ports. Called from.github/workflows/ci.ymlL57,.github/workflows/release.ymlL74,.github/workflows/tmux-matrix.ymlL119 and.github/workflows/clojure-compatibility.ymlL79. -
.github/scripts/tmux_build.pywith.github/scripts/test_tmux_build.py: builds and caches a tmux per lane (.github/workflows/tmux-matrix.ymlL133,.github/workflows/clojure-compatibility.ymlL88). It is 0.89 to 0.91 similar to the copies in the dotnet, go and ts ports. -
tools/ci/plan.pywithtools/ci/test_plan.py: plans the tmux matrix (.github/workflows/tmux-matrix.ymlL90) by matchingval lanes = listOf(...)in a Gradle plugin with a regular expression (tools/ci/plan.pyL26-L34). Read a manifest that Gradle and the planner share instead. - The macOS tmux build written inline in
.github/workflows/clojure-compatibility.ymlL178-L197: a fourth tmux build path besidetmux_build.py.- Left open:
libtmux/.github/actions/build-tmuxinstalls its dependencies with apt and has no macOS support, so this step stays until the action gains it. The Linux build in the same workflow uses the action.
- Left open:
Remove shell setup once the API lands
- libtmux-java#142:
examples/api/run.shcreates a private socket directory, starts tmux, removesTMUX,TMUX_PANEandLIBTMUX_SOCKET*, creates thework-oneandwork-twosessions, and stops the server (examples/api/README.mdL17-L22). Delete it whenlibtmuxcan start and own a private server. The Clojure examples run through the same launcher (examples/api/README.mdL128).
Keep
tools/mcp-swap(tools/mcp-swapis Java and outside SCRIPTS.md #174): a Gradle subproject thatcheckformats, compiles and tests like a library module. It stays Java, because a Python copy would be a second implementation of its transaction and recovery contract;.github/SCRIPTS.mdrecords the exception and.github/CONTRIBUTING.mdnames the maintainer task.gradle/clojure-runner/libtmux/internal/test_runner.clj,gradle/clojure-runner/libtmux/internal/api_reference.cljandgradle/clojure-runner/libtmux/internal/guard_probe.clj: the Clojure modules' test runner, API reference generator and namespace-guard probe. Gradle runs them (build-logic/conventions/src/main/kotlin/libtmux.clojure-library.gradle.ktsL92,build-logic/conventions/src/main/kotlin/libtmux.clojure-library.gradle.ktsL110,build-logic/conventions/src/main/kotlin/libtmux.clojure-library.gradle.ktsL128,build-logic/conventions/src/main/kotlin/libtmux.clojure-library.gradle.ktsL192) and so do thedeps.ednaliases (deps.ednL8-L23). They load Clojure namespaces and read their vars, which a Python script cannot do.gradlewandmodule-tests/sbt/sbtw: vendored build-tool wrappers, not support scripts. CI validates the Gradle wrapper jar (.github/workflows/ci.ymlL70-L74).
Acceptance
No Python libtmux or tmuxp install, fetch or import remains, outside attribution in MIGRATION.md, the changelogs and the guides:
$ rg -l 'import libtmux|tmux-python/libtmux|pip install (libtmux|tmuxp)|tmuxp==|TMUX_WORKSPACE_TEST_PYTHON'Nothing refers to the deleted module or the ledgers:
$ rg -l 'tools[./]ci[./]tmux_ref|test_tmux_ref|docs/parity|python-api\.md|test-map\.md' .github tools docs build-logicexamples/api/run.sh is gone:
$ fd run.sh examplesCI runs ruff format --check, ruff check, ty check and pytest over every kept script under scripts/, and each has a README.md and tests/.
References
.github/SCRIPTS.md- libtmux/docs#323,
notes/decisions/port-support-scripts.md - libtmux-java#142, No API starts a private tmux server, so examples need
run.sh
Activity
tony commentedon Nov 15, 2026
Ten checklist items and the missing-API item (#142) landed on
masterthrough986df201. Two stay open:workspace-cliPython bridge uses until Decide whether the workspace CLIs keep their tmuxp and Python libtmux bridge docs#324 decides what happens to the bridge. Theimport libtmuxfloor assertion is deleted.clojure-compatibility.yml. The sharedbuild-tmuxaction installs its dependencies with apt and has no macOS support, so the step stays until it does.#174 is decided:
tools/mcp-swapstays Java,.github/SCRIPTS.mdrecords the exception and.github/CONTRIBUTING.mdnames the maintainer task. The first option of #174 (delete it) and the second (move it to Python) were not taken; either is a one-commit follow-up if the maintainer prefers it.tony commentedon Nov 16, 2026
Item from the independent script review, added here so the commit that fixes it can reference this issue:
ProcessTest.javaembeds Python child programs in text blocks. Move each into a checked.pytest resource that the ruff and ty steps cover, with test behaviour unchanged.tony commentedon Nov 16, 2026
The
ProcessTestitem is onmasterat 952b8d2; every workflow at that head passed (CI https://github.com/libtmux/libtmux-java/actions/runs/43791280060, tmux matrix https://github.com/libtmux/libtmux-java/actions/runs/43791279687).ProcessTest.javatext blocks are checked.pytest resources underlibtmux-workspace-cli/src/test/resources/io/github/libtmux/workspace/cli/probes, loaded by the test, and covered by the ruff format, ruff check and ty steps of thescriptsjob. All 24ProcessTesttests pass locally; a probe changed to answer the wrong key fails its test.The commit was pushed before the instruction to cite the issue, so it carries no
Refsline.integration-tests/.../NativeClient.javastill embeds one Python program; it was outside this item.