tmuxp compatibility and port status

Edit this page on GitHub

github.com/libtmux/libtmux-go/workspace · Source

Local implementation, unpublished. The Go 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

Native services cover load, capture, discovery, search, conversion, both importers, editor execution and diagnostics. Load creates or reuses a session, or appends to the current pane’s session. Human foreground loading offers switch/detach/append choices inside tmux and requires terminal stdin. Machine load requires -d or --append and does not prompt. Native before-script arguments validate for all inputs before session mutation. A failed native script removes an owned newly created session and preserves a borrowed append session. With several inputs, load -s changes only the final workspace’s session name; earlier inputs retain their configured names in native and Python-bridge execution.

Before foreground loading, the CLI opens the controlling terminal outside tmux, or verifies the inherited server, pane and input terminal inside tmux. Switching requires one identifiable terminal client viewing that pane. Multiple matching clients and independent active-pane clients on the same physical window require detached or append mode. The selected client’s identity and attachment are checked again before switching.

Progress stops and both output streams are flushed before handoff. A failed prompt flush stops before input is read. Handoff failures retain completed workspace results for diagnostics. These checks do not make the later tmux client-name operation atomic with client replacement.

Append checks the inherited server PID and selected socket before checking Python. Socket paths may contain commas. It retains one session across all inputs even if a script moves the invoking pane; linked panes use tmux’s canonical session. Native build entry rechecks that retained session before running a before script, and subsequent commands retain the core’s daemon replacement checks.

Legacy -8 and --88-colors fail before workspace lookup, runtime checks or backend mutation. -2 requests 256-color mode.

The normalizer supports pane and command shorthand, inherited commands, sequential enter/delay settings, history suppression, directories, launch-time environment, shell overrides, layouts, indexes, focus, options, before-scripts and readiness policies. Conversion preserves extension fields. Explicit saves use atomic publication and require --force for replacement. Capture warns that original arguments, history, scripts and plugins cannot be recovered.

Every command accepts --json and --ndjson; NDJSON takes precedence. Load streams sequenced events and a terminal result. Human load has semantic colors and terminal progress with presets, custom tokens and bounded script lines. Machine output disables terminal rendering. Documentation, command metadata, manuals and shell completion can be generated from the command graph.

ls --tree groups workspaces by directory in discovery order. --full includes their YAML configurations. Human names and paths escape terminal controls; machine records preserve the underlying values and ignore tree presentation.

SIGINT and SIGTERM cancel active scripts through normal cleanup and return status 130. Unix confirmation and destination prompts also cancel while stdin remains open, preserving terminal settings. Progress follows terminal resizing.

Native Go logging supports --log-level and structured --log-file output on Unix. Optional diagnostics follow the selected level; mandatory command errors and machine results remain visible. A later log write or close failure preserves the workspace outcome and attempts at most one optional warning. See the logging contract.

Search uses native Go regular expressions with ASCII word boundaries and JSON text for structured commands. --regex-engine python explicitly selects a checked Python runtime for Python regex syntax and representations. Python shell, plugin and custom-builder execution checks tmuxp 1.74.0 through TMUX_WORKSPACE_PYTHON; ordinary native commands do not require that runtime. Plugin and custom-builder append use the retained session, including when the caller also supplies -d. The adapter checks its daemon and session before importing extensions and after constructing the builder. A missing or replaced target fails without creating a replacement session; errors retain the original session ID. These checks do not make later builder execution atomic against external server replacement or arbitrary plugin code. Documents without a before_script key can add windows through that bridge.

The local source reference is workspace/CLI.md. Use the native executable’s --help for the options implemented in that checkout.

Remaining gapsLink to section

• Selecting plugins, workspace_builder or workspace_builder_paths with --append and a document before_script key is unavailable and fails during preflight, including an empty or null script value. The checked Python builder can delete a borrowed session on script failure; the CLI blocks that combination before runtime checks or session mutation. Native scripted append and plugin append without a document script remain supported.
• Script lifecycle failures and effects before an input returns from building need additional coverage.
• Descendant cleanup across platforms, optional Python terminals, complete configuration/importer coverage and installed completion execution remain acceptance gaps.

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 20 upstream YAML examples and built 18 in the original audit. First-pane environment was applied too late; pane environment and split shell inheritance were incomplete. Explicit zero delay could inherit a nonzero value. YAML/JSON serialization needed a document-preserving boundary. The source snapshot had no native CLI.

At that baseline, the workspace package rejected unknown fields, did not perform tmuxp variable expansion or run Python plugins, and could leave partial state after a builder error. These historical library limits do not describe the current CLI normalizer, document conversion or explicit Python bridge.

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

Python libtmux exposes LIBTMUX_TMUX_FORMAT_SEPARATOR in its format collector. This native CLI does not claim that setting as a supported codec control. Its framing and decoding need their own compatible seam and collision, empty value, Unicode and line-break checks before accepting such a setting.

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.

tmuxp reference source.