Use the TypeScript workspace builder

Edit this page on GitHub

@libtmux/workspace 0.1.0-alpha.10 · Source

Apply a workspace to create its session, windows, and panes. Install tmux on the host, then add the workspace package and core library:

$ bun add @libtmux/workspace libtmux

Create a sessionLink to section

Save this as workspace.ts. It creates a dedicated session with two panes. The try / finally removes that session after inspecting it, so the example leaves no session running.

import { Server } from "libtmux";
import { applyWorkspace } from "@libtmux/workspace";

const server = new Server({
  socketName: `workspace-guide-${crypto.randomUUID()}`,
});
const session = await applyWorkspace(server, {
  session_name: "workspace-guide",
  windows: [{ window_name: "editor", panes: ["echo ready", "echo ready"] }],
});
try {
  console.log(session.name);
} finally {
  await session.kill();
}

Run it with Bun:

$ bun run workspace.ts

The example selects a new socket name so it does not reuse a session on your normal tmux server. For a workspace you want to keep, choose the intended server explicitly and retain the returned session.

Read configurationLink to section

parseWorkspace from @libtmux/workspace/config validates an object produced by your chosen JSON or YAML parser. parseWorkspaceYaml reads YAML through Bun’s parser. Unknown fields fail validation rather than silently changing the requested workspace.

Use planWorkspace before changing an existing session. Review removal and retention entries, then apply promptly. Replan after any failure or outside change. See Topics for command replay and pruning policies and Examples for the package’s integration example.

Parsing implementation; Application implementation.