Workspace Manager for TypeScript (in development)

TypeScript

@libtmux/workspace 0.1.0-alpha.10 · Source

Install

Install the workspace package separately from the core library.

$ npx -y @libtmux/workspace-cli --help

Runs tmux-workspace without installing it. Pass a command such as load ./workspace.yaml in place of --help.

$ bunx --bun @libtmux/workspace-cli --help

--bun runs the command on Bun. Without it, bunx runs the command on Node when Node is installed, because its shebang names node.

$ pnpm dlx @libtmux/workspace-cli --help

$ yarn dlx @libtmux/workspace-cli --help

Yarn refuses a release younger than its npmMinimalAgeGate, one day by default.

$ npm install -g @libtmux/workspace-cli

Puts tmux-workspace on PATH, so a workspace loads with tmux-workspace load ./workspace.yaml.

$ pnpm add -g @libtmux/workspace-cli

$ bun add -g @libtmux/workspace-cli

Command reference

Every command, flag and compatibility target.

Configuration

Workspace fields, normalization and execution.

Install and load

Load a workspace on a private socket, then capture it.

Example gallery

Workspace files to start from, with their prerequisites.

Compatibility

What is implemented, and where it differs from tmuxp.

Internals

The workspace library, for building sessions from code.

Native services load/reuse/append and capture sessions, discover and search documents, convert formats, import configurations and run editors. Loading includes terminal attach/switch, before scripts, progress and diagnostics. Python shell evaluation and explicit plugin/custom-builder loads use an optional tmuxp bridge. Ordinary native loads do not start Python. Native command metadata and Bash, Zsh and fish completion come from the parser; completion starts no Node, Bun or tmux process.

Load a workspace from the terminalLink to section

Install runs the @libtmux/workspace-cli prerelease from npm without installing it, or installs it to put tmux-workspace on PATH. The installation walkthrough loads a small workspace on a private socket. Inspect the command without starting tmux:

$ npx -y @libtmux/workspace-cli --help

Use detached load for the walkthrough. JSON and NDJSON output are available; choose the mode explicitly when scripting. The command/configuration reference below also documents tmuxp behavior and compatibility targets, so it is not a claim that every referenced feature works in this implementation.

Current coverageLink to section

Interactive prompts and complete configuration/platform acceptance remain unfinished. Python extensions require tmuxp 1.74.0 and report observed effects without claiming ownership or rollback. See hooks and builders for append restrictions. Capture reports live state rather than recovering the original workspace commands or extension intent.

For the released Python workflow, use tmuxp and its Python workspace guide. It is a separate application and remains useful when a required native feature is incomplete.

Start hereLink to section

The @libtmux/workspace library package remains available for applications that build sessions through code. Internals documents that API:

Guides show application setup and builder calls.
Topics explain supported configuration and behavior.
Examples exercise the library or source consumer.
API covers the builder and configuration interfaces.

tmuxp command and configuration referenceLink to section

Use the CLI’s help and the limits above when applying these compatibility references to native execution.

Installation walkthrough installs and runs the published native CLI.
Inspect through MCP connects to the loaded session.
Command reference lists tmuxp commands, flags and compatibility targets.
Configuration covers fields, normalization and execution.
Example gallery includes upstream fixtures and prerequisites.
Compatibility status records builder/reference gaps.
JSON, NDJSON, and color describes the shared output design.