TypeScript workspace builder API
@libtmux/workspace 0.1.2 · Source
Import planning and application from @libtmux/workspace, and parsers from
@libtmux/workspace/config. Application operates
on a core libtmux Server supplied by the caller; creating that server does
not choose a workspace or apply one automatically.
Parse and validate¶
parseWorkspace validates data already
read by your application.
parseWorkspaceYaml
adds Bun’s YAML parsing. Both produce the workspace configuration consumed by
the builder.
Plan and apply¶
planWorkspace returns a description
of membership changes. WorkspacePlan
records creations, removals, renames, and retained surplus.
applyWorkspace performs the work and
resolves to the resulting Session. Its options control pruning and whether
commands run in existing panes. Planning accepts pruning policy; command
policy belongs to application.
Handle failure¶
WorkspaceApplyError preserves
the cause and completed milestones. Reinspect tmux before retrying; the error
is not a transaction log of every effect or a receipt for shell commands.
The language API builds workspaces directly. Availability through an MCP server is a separate protocol capability; consult this port’s MCP section for its advertised tools.
API declarations
Follow a declaration for its signature, members, documentation, and source.
Workspace files
config.initialPaneStartDirectory- The directory tmux needs when it creates the session's first pane.
config.optionValue- Convert a YAML scalar to the string tmux accepts for an option value.
config.paneCommands- Normalize a pane entry to the commands it should run, in order.
config.paneStartDirectory- A pane's start directory, falling back to its window's and then the session's.
config.paneWantsFocus- Whether a pane entry asked to be the focused one.
config.parseWorkspace- Validate a parsed workspace, rejecting anything the schema does not allow.
config.parseWorkspaceYaml- Parse a YAML or JSON workspace, then validate it.
config.windowStartDirectory- A window's directory, inherited from its workspace when it has none.
config.Workspace- A validated workspace with every schema default and transform applied.
config.WorkspaceInput- Workspace data before schema defaults and transforms are applied.
config.WorkspaceOptionValue- A value tmux stores for a session or window option.
config.WorkspacePane- A pane: a bare command string, or the settings the pane is created with.
config.WorkspaceWindow- A window with every schema default applied.
config.WorkspaceWindowInput- A window as written, before panes defaults to one implicit pane.
Building and freezing
builder.applyWorkspace- Build a workspace into a real tmux session, or reconcile one that exists.
operation_options.ApplyWorkspaceOptions- How applyWorkspace should treat a workspace that is already running.
ownership.claimSession- Claim a session this apply created.
operation_options.CommandPolicy- When a pane's shell_command entries are sent to it.
ownership.mayPrune- Whether surplus topology may be removed.
ownership.ownedByWorkspace- Whether this session carries the mark for name.
builder.planWorkspace- Plan session, window, and pane membership without changing tmux.
operation_options.PlanWorkspaceOptions- Structural planning options; pane command delivery is apply-only.
ownership.PrunePolicy- What to do with windows and panes the workspace does not describe.
builder.WorkspaceApplyMilestone- A high-level apply operation that finished before a later one failed.
builder.WorkspaceApplyStage- The high-level operation an apply was attempting when it failed.
planning.WorkspacePaneCreation- Panes that applying would create in one window position.
planning.WorkspacePaneRemoval- Existing panes that applying would destroy.
planning.WorkspacePlan- Session, window, and pane membership changes an apply would make.
planning.WorkspaceRetention- Surplus topology retained because removing it would exceed the policy.
planning.WorkspaceWindowCreation- A window that applying would create.
planning.WorkspaceWindowPlacement- One existing window placement named by a workspace plan.
planning.WorkspaceWindowRemoval- How applying would remove an existing window placement.
planning.WorkspaceWindowRename- One existing window rename, identified independently of its current name.
Errors
builder.WorkspaceApplyError- Applying stopped after tmux may already have changed.