TypeScript workspace builder API

TypeScript

@libtmux/workspace 0.1.0-alpha.10 · 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 validateLink to section

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 applyLink to section

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 failureLink to section

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.

Public exports

API declarations

Follow a declaration for its signature, members, documentation, and source.

Exports

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.
config.initialPaneStartDirectory: The directory tmux needs when it creates the session's first pane.
ownership.mayPrune: Whether surplus topology may be removed.
config.optionValue: Convert a YAML scalar to the string tmux accepts for an option value.
ownership.ownedByWorkspace: Whether this session carries the mark for name.
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.
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.
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.
builder.WorkspaceApplyError: Applying stopped after tmux may already have changed.
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.
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.
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.
config.WorkspaceWindow: A window with every schema default applied.
planning.WorkspaceWindowCreation: A window that applying would create.
config.WorkspaceWindowInput: A window as written, before panes defaults to one implicit pane.
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.