tmuxp compatibility and port status
workspace consumer 0.1.0-alpha.10 · Source
Local implementation, unpublished. The C++ 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 optional application provides native ls, search, edit, convert,
import teamocil, import tmuxinator, debug-info, load and freeze.
The optional shell invokes an installed
tmuxp 1.74.0 executable through native process and terminal handling. Select
the executable with PATH or TMUX_WORKSPACE_TMUXP; native loading does not
require Python. Machine shells require -c and retain structured output.
Loading starts tmux when needed, creates sessions or reuses exact names. It retains created object identities and supports command settings, directories, environment, shells, layouts, indexes and focus. A session-name override applies to the final input. Failed builds remove their own session and preserve earlier successful inputs. Cold startup verifies the daemon and bootstrap session; uncertain identity is reported as possibly retained state. Append authenticates the inherited daemon and current pane, preserves existing windows and reports new windows/settings retained after failure.
Ordinary human load requires a foreground controlling terminal before mutation.
Outside tmux it attaches; inside tmux it switches the unique non-control client
viewing the invoking pane. Zero or multiple matching clients are refused with
-d guidance. The final input selects the destination, including a reused
session. Machine load requires -d or --append.
Independent active-pane focus on the invoking physical window requires -d
or --append, including linked windows. This check runs before loading and
handoff; clients on other physical windows do not block switching.
Load flushes both output streams before handoff and retains loaded changes on
handoff failure. It rechecks the selected client’s identity before switching;
tmux’s name-targeted switch still leaves a race after that check. Attachment
needs a standard stream identifying the concrete controlling tty. With all
three standard streams redirected, use -d. See load.
before_script invokes quoted argv directly, after session creation or append
selection and before workspace settings and windows. Reusing a session skips
the script. All inputs’ script arguments, directories and environment names
are validated before creation. The working directory is the configured session
directory, or the invoking directory when omitted.
Script stdin is closed. Each output stream retains up to 1 MiB; NDJSON also emits script-output records while the child runs. Script failure or an output limit removes only a newly owned session. Append preserves its borrowed session and reports partial effects. Interruption joins the child group, and remaining group processes are terminated when the script exits. No fixed script deadline is imposed.
Conversion preserves extension fields. Imports validate source shapes and
translate supported command grouping, roots, layouts, focus and options.
Unsupported lifecycle, title and synchronization behavior is refused before
saving. See native imports.
Capture records current commands, directories, window names, indexes, focus,
layouts and local session/window options. Indexed options and escaped values
survive reload; synchronize-panes is restored after pane creation. Inherited
and global options and environment are omitted. Capture warns about
unrecoverable original arguments, history and scripts. Search uses native C++
ECMAScript regular expressions.
Layout syntax is checked across all inputs before scripts or session creation. Named-layout and JSON-format availability follow the running daemon’s version, or the selected client when starting a new server. Saved layouts accept legacy checksum strings and JSON v2 from tmux next-3.9, including floating-pane metadata. Custom layout checks validate syntax and pane capacity; tmux owns geometry and pruning to the requested pane count.
Every command accepts --json and --ndjson; NDJSON takes precedence. Load
flushes events and a terminal result. Diagnostics use stderr and control bytes
remain escaped in machine strings. Explicit saves publish an owned temporary
file and require --force for replacement. load -2 selects 256-color mode;
-8 fails before document lookup or tmux access.
Human load progress uses terminal stderr, five presets or a custom template.
Counters track delivered pane commands and configured delays, not program exits.
--progress-lines bounds the script panel; failure retains its final bounded
tail. Redirected stdout receives script output once. Without the panel, both
script streams flush to their original destinations as data arrives.
Machine output, redirected stderr, TERM=dumb and explicit progress disabling
suppress the panel. Resize clears it and restores ordinary stream delivery.
Progress preserves cursor visibility and terminal modes. Interruptions cancel
configured delays and check between topology, command, option and focus steps.
load --log-file PATH appends JSON diagnostics. --log-level defaults to
warning; info includes load lifecycle records and debug adds script-output
chunks. Required errors and machine results remain visible at every level.
Invalid file destinations fail before mutation; later file errors preserve
command status, cleanup and handoff. See logging.
Native Bash, Zsh and Fish completion covers nested commands, flags, enumerated values and file paths. Dynamic session/configuration-name discovery remains unavailable. See completion.
The editor receives parsed argv directly, using VISUAL, then EDITOR, then
vi. It can take the controlling terminal while machine stdout stays separate.
Without a terminal, output is bounded; exceeding the limit terminates the owned
child group. SIGINT/SIGTERM cancel captured children and their pipe-owning
descendants. Suspend/resume and non-Linux behavior need further validation.
The local source reference is apps/workspace/README.md. Use the native
executable’s --help for the options implemented in that checkout.
Remaining gapsLink to section
- Python plugins and custom builders are unavailable.
- Windows created by arbitrary scripts are outside the builder’s retained-window records, including when a borrowed append session survives script failure.
- Dynamic session/configuration-name completion remains unavailable.
- Additional importer fields, full configuration/capture coverage and supported-platform packaging remain open. Append’s first explicit window index must name a free slot in the existing session.
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 21 upstream YAML examples in the original audit. Live probes
found gaps in index assignment and command routing, first-pane environment,
split shell inheritance and options_after timing. The source snapshot had no
native CLI.
At that baseline, the workspace consumer was a source-tree library target. Its YAML parser rejected fields outside its supported subset, and builder failures could leave earlier tmux changes in place. These historical library results do not describe the current CLI’s owned-session cleanup and append reporting.
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.