tmuxp compatibility and port status
@libtmux/workspace 0.1.0-alpha.10 · Source
Local implementation, unpublished. The TypeScript tmux-workspace CLI
is available in the workspace-cli source worktree. Its command and
configuration coverage remains partial. See installation
for local setup; installing a published library does not establish availability
of this CLI.
Compatibility targets useful tmuxp 1.74.0 commands and workspace workflows, with native validation, execution and output conventions. Matching command names does not promise identical runtime behavior or Python semantics.
This portLink to section
The CLI runs on Node.js and Bun. Native services cover detached load, exact session reuse, append, capture, discovery, search, conversion, both importers, editor execution and diagnostics. Attached load uses the controlling terminal and selects its tmux client before building; unavailable terminals fail before session creation. Append authenticates the inherited server and current pane. A failed native bootstrap removes its created session and preserves a borrowed append session. Other failures report completed objects and the failed stage.
Native loading supports command settings, directories, environment, shells,
layouts, explicit window indexes, focus, options and before-script execution.
Blank panes skip readiness checks. Conversion preserves extension fields;
explicit saves require --force to replace an existing file. Capture recovers
live state but cannot recover original command arguments, history or plugin
intent. Native JavaScript regular expressions power search.
Capture accepts an explicit session name or ID, authenticated tmux context, or
the only live session. Multiple sessions without context require an explicit
target. A .json destination selects JSON unless -f overrides it; other
destinations default to YAML. --quiet suppresses human save status while
preserving machine results.
Every command accepts --json and --ndjson; NDJSON takes precedence. Machine
load requires -d or --append and never prompts. Human output has semantic
colors and terminal progress with preset or custom formats. Log levels filter
diagnostics, and load --log-file records them separately from result output.
Child streams are bounded, escaped and streamed in NDJSON. load -2 selects
256-color mode; -8 fails before workspace lookup or tmux access.
Python shell and explicit plugin/custom-builder loads require tmuxp 1.74.0 in
the interpreter selected by TMUX_WORKSPACE_PYTHON, defaulting to python3.
An interactive shell needs a controlling terminal. Ordinary loads and native
read commands do not start Python. Empty plugin lists and blank builder names
stay native.
The load adapter expands common fields and resolves existing import directories
relative to the workspace file. Explicit custom builders may omit windows.
Append retains its authenticated target across inputs and rejects Python
before_script. Extension progress shows a workspace label and script output
without native pane counters.
Extension results report effects_scope: "observed", effects_unknown: true,
and newly observed window and pane IDs. Concurrent changes may appear in these
observations; the CLI does not infer ownership or roll back extension effects.
Cancellation stops the owned Python process group, then allows up to one second
to observe surviving topology. A daemon change or failed observation is reported
without comparing IDs across daemon lifetimes.
Native command references and Bash, Zsh and fish completion are generated from
the parser. completion prints the selected shell script; machine modes return
a structured script result. Static completion covers commands, options, enum
values and file paths without running the CLI. Saved workspace names and live
session values are outside its scope. Linux checks use Bash 5.2, Zsh 5.9 and
fish 4.8; older shells and newline filenames remain unverified.
Bare root/import groups in machine modes return a structured usage error with status 2 and empty stdout. Explicit help requests still print help.
The local source reference is packages/workspace-cli/README.md. Use the native
executable’s --help for the options implemented in that checkout.
Remaining gapsLink to section
- Interactive confirmation prompts remain unfinished.
- Complete configuration/importer coverage, recoverability-aware capture and platform acceptance remain open. Local installed-package checks on Node and Bun do not establish support for every platform or workspace example.
Historical builder auditLink to section
Audit date: 2026-09-09. Native source snapshot. The following results describe that original library revision, before the local CLI implementation. They are historical evidence, not its current capability list or a support guarantee for a published artifact.
The library parsed 8 upstream YAML examples in the original audit. Its reconciliation builder could remove existing windows and panes, unlike tmuxp load policy. Capture/replay preserved the measured topology and directories, but was not a complete freezer. The source snapshot had no native CLI.
At that baseline, @libtmux/workspace validated a strict subset. Its apply
operation used ownership and command policies. Its YAML helper required Bun;
Node callers needed a separate YAML decoder. These library observations do not
describe the current CLI’s YAML support or loading policy.
Read the port’s builder topics and API for its library interface. Use the language switcher to compare the same topic across ports; each port has its own coverage limits.
Shared gapsLink to section
Parser acceptance does not prove execution support. Native regex engines and Python plugin runtimes have different contracts; identical flags alone do not establish compatibility. See shell, search and hooks, and apply this port’s current limitations above when reading those reference pages.
Optional format separatorLink to section
The TypeScript library reads LIBTMUX_TMUX_FORMAT_SEPARATOR when importing its
FORMAT_SEPARATOR constant for direct format-list consumers. The workspace
CLI’s snapshot codec uses separate guarded framing; this setting does not change
that transport or its decoding.
Reading examplesLink to section
The gallery contains the upstream fixture corpus. Parsing a fixture and executing its applications are separate checks. Several require external programs, remote hosts, project directories or plugin packages. A successful YAML read does not establish those dependencies or the complete workspace behavior.