Workspace guide

libtmux-workspace 0.1.2 · Source

mLoad bounded YAML or JSON, inspect an immutable Ccreation plan, then explicitly mapply it to an open libtmux server.

API reference · Command reference · Guides · RubyGems

Part of libtmux for Ruby. Built on libtmux.

Check a workspace file, see the ordered steps a load would run, and create the session on a running tmux server, from the libtmux-workspace command or from Ruby.

Validation and offline planning need no running daemon, and imports start no tmux process.

Contents — Quick start · Write the file · Create the session · Failed apply · Attach or switch · Scripts · Leaves out · Support · Documentation

Quick start¶

Install the gem and its libtmux-workspace executable. It needs Ruby 3.3 or newer, and tmux 3.3a or newer to load a plan:

$ gem install libtmux-workspace

Save this declared subset of tmuxp-style data as workspace.yaml. Relative directories resolve against the configuration file’s directory.

session_name: work
environment:
  PROJECT_MODE: development
windows:
  - window_name: editor
    window_index: 1
    layout: tiled
    panes:
      - shell_command: printf 'editor ready\n'
      - {}

Check the file. validate reads no tmux state:

$ libtmux-workspace validate workspace.yaml

Workspace configuration is valid.

Print the ordered operations a load would run. Offline plan does not contact tmux either:

$ libtmux-workspace plan workspace.yaml

offline_create: 11 ordered steps
1. create_session session (creation)
2. set_session_option session (configuration)
3. set_window_option window:0 (configuration)
4. move_initial_window window:0 (configuration)
5. split_pane pane:0:0 (creation)
6. select_layout window:0 (configuration)
7. send_command pane:0:0 (dispatch_only)
8. unset_window_option window:0 (configuration)
9. select_pane pane:0:0 (configuration)
10. select_window window:0 (configuration)
11. unset_session_option session (configuration)

Write the file¶

mWorkspace.load: the declared subset¶

$load reads a regular file of bounded size and infers JSON or YAML from its extension. mWorkspace.parse takes the text and a base directory instead. Both return an immutable workspace:

• Root: #session_name, nonempty windows, options, window_options.
• Window: #window_name, nonempty panes, #window_index, focus, mlayout, options.
• Pane: a command string, or a mapping with focus, split and msize.
• Root, windows and panes accept start_directory, environment, shell_command and shell_command_before.
• Layouts are even-horizontal, even-vertical, main-horizontal, main-vertical and tiled.
• At most one window and one pane per window declare focus.
• Without a filename, the command looks for exactly one .tmuxp.yaml, .tmuxp.yml or .tmuxp.json in the current directory.
• An unknown field or an unsupported feature fails with a CConfigError that names its position in the file.
• YAML tags, anchors and aliases are rejected, and no Ruby, ERB, plugins or callbacks run.
• ${NAME} substitution is opt-in: pass expand_environment: true, environment: {"NAME" => "value"} to load or mparse, or --expand-environment --env NAME=VALUE to the command.
• mworkspace.to_h exports an immutable, normalized and reloadable configuration, with expanded values and absolute directories.

The full field, option and limit lists are in Workspace parsing.

Create the session¶

libtmux-workspace load: build it on a running server¶

$load needs a running server. It never starts one, so start a private server with a keepalive session and no user configuration:

$ WORKSPACE_TMP=$(mktemp -d)

$ tmux -S "$WORKSPACE_TMP/tmux.sock" -f /dev/null new-session -d -s keepalive

Create the workspace’s session on that socket. It stays detached:

$ libtmux-workspace load \
    --socket "$WORKSPACE_TMP/tmux.sock" \
    workspace.yaml

Workspace created; 11 steps completed. Shell commands were dispatched.

The new work session holds the editor window:

$ tmux -S "$WORKSPACE_TMP/tmux.sock" list-windows -t work

Stop only the private server and remove its directory:

$ tmux -S "$WORKSPACE_TMP/tmux.sock" kill-server

$ rm -rf "$WORKSPACE_TMP"

Loading the same file again fails with status 1: a plan creates a new session and never reconciles an existing one.

mPlan#apply: the same from Ruby¶

mWorkspace.load reads the file, mworkspace.plan plans it against a snapshot, and mapply creates the session. Calling apply authorizes the configuration’s shell commands.

The example file writes the same document to a temporary workspace.yaml before loading it, so it runs saved on its own:

require "libtmux"
require "libtmux/workspace"
require "tmpdir"

document = <<~'YAML'
  session_name: work
  environment:
    PROJECT_MODE: development
  windows:
    - window_name: editor
      window_index: 1
      layout: tiled
      panes:
        - shell_command: printf 'editor ready\n'
        - {}
YAML

Dir.mktmpdir("workspace-") do |directory|
  path = File.join(directory, "workspace.yaml")
  File.write(path, document)
  LibTmux::Server.start do |server|
    workspace = LibTmux::Workspace.load(path)
    plan = workspace.plan(snapshot: server.snapshot)
    puts "planned steps: #{plan.steps.length}"
    result = plan.apply(server: server)
    puts "applied: #{result.success?}"
    puts "sessions: #{server.list_sessions.map { |session| session.snapshot.name }.join(', ')}"
  end
end

The program runs on a private server and prints:

planned steps: 11
applied: true
sessions: work

• A snapshot makes the plan reject a name that already exists, and every apply takes a fresh snapshot and checks again.
• The plan creates a new session. It does not reconcile, replace or remove an existing one.
• Success shows that tmux accepted the dispatch of each shell command. It does not show that the command finished.

The complete program also runs the installed command with --switch. The contract is in Workspace apply.

Recover from a failed apply¶

mApplyError#result: what exists after a failure¶

A failed apply raises CApplyError. Its immutable mresult holds the completed step IDs, the mcreated_refs tmux returned, the effects it observed, and the failed action. Pass compensate: true to remove only the session the apply created:

require "json"
require "libtmux"
require "libtmux/workspace"

LibTmux::Server.start do |server|
  server.new_session(name: "borrowed", command: ["/bin/cat"])
  crowded = LibTmux::Workspace.parse(
    JSON.generate({session_name: "crowded", windows: [{window_name: "small", panes: Array.new(40) { {} }}]}),
    format: :json, base_directory: __dir__
  )
  begin
    crowded.plan.apply(server: server, compensate: true)
  rescue LibTmux::Workspace::ApplyError => error
    puts "failed action: #{error.result.failed_action}"
    puts "created a session: #{error.result.created_refs.key?('session')}"
    puts "compensation: #{error.result.compensation}"
  end
  puts "sessions: #{server.list_sessions.map { |session| session.snapshot.name }.join(', ')}"
end

That many panes do not fit in one window, so tmux refuses a split after the session exists. It prints:

failed action: split_pane
created a session: true
compensation: completed
sessions: borrowed

• Compensation removes the new session only after a tmux guard shows that every window and pane in it has a positively identified created reference.
• An unknown initial entity, or a borrowed entity moved into the session, makes it refuse.
• Compensation cannot undo what shell commands did. Without it, the partial state stays for you to inspect.
• Diagnostics omit command payloads and paths. Names are never used to guess ownership.

The command takes --compensate. The contracts are in Workspace results.

Attach or switch to the new session¶

load --switch: move a client to the session¶

• load --attach opens the CLI’s /dev/tty after creation and runs an owned terminal client until you detach. It requires a valid TERM.
• load --switch CLIENT switches a current tmux client to the created session after apply, keeping the session’s environment.
• CLIENT is a client name, a full TTY path or a TTY path without /dev/. Use --switch=VALUE for a selector that begins with -.
• A missing client, or a failure to open or attach the terminal, keeps the created session and returns status 3.
• Attach and switch are mutually exclusive, and neither infers a latest client. The library’s mPlan#apply does neither.

The selector rules are in Client switching.

Script it¶

--json: one object on stdout¶

Check the installed gem version without reading a configuration or contacting tmux:

$ libtmux-workspace --version

Human plans list ordered operations and their effects. --json prints the same plan data as mPlan#to_h, including configured command text and paths:

$ libtmux-workspace plan \
    --json \
    workspace.yaml

load and $plan --live act on an existing server. Without --socket, they use the socket in LIBTMUX_SOCKET_PATH, else the name in LIBTMUX_SOCKET, else the server TMUX names when run inside tmux, else tmux’s default socket. When both variables are set, the path wins, an empty variable counts as unset, and --socket ignores both. A command run from a tmux pane with none of these set acts on that pane’s server. This detached creation example names its socket with a TMUX_SOCKET value:

$ libtmux-workspace load \
    --socket "$TMUX_SOCKET" \
    --json \
    workspace.yaml

libtmux-workspace --help lists every option. The command reference has a page for each command.

Apply errors include mApplyResult#to_h. Human errors write the diagnostic and any ledger to stderr. Diagnostics omit configuration payloads; plan rendering and canonical export contain those values by design.

What it leaves out¶

• Reconciliation. A plan creates a new session and never replaces or removes an existing workspace. The contract is in Workspace plans.
• Shell command completion. Apply records a shell command as dispatched. Embedded newlines can execute while the text is inserted. See Workspace apply.
• Rollback of shell effects. Compensation removes only tmux objects the apply created. See Workspace results.
• Features beyond the declared subset. Plugins, ERB and callbacks are rejected, and a CConfigError names the position.
• A guessed client. Attach and switch need an explicit client. See Client switching.

Support and status¶

Releases are numbered 0.1.N, and each release increments N. The API is not settled: any release may change or remove exported identifiers, and the changelogs mark each break. Pin an exact version to avoid one. See the changelog, and the main changelog for changes that span gems.

• Ruby 3.3 or newer. The gem depends on the same version of libtmux, JSON 3.0 and Psych 5.5.
• tmux 3.3a or newer to load or apply a plan.
• Older daemons. $load creates nothing and prints the refusal with the floor and the remedy. With --json, the refusal is in error.message and error.kind is tmux_unsupported.
• Linux, including WSL, and macOS. The library and the command share the core compatibility workflow: Ruby 3.3, 3.4 and 4.0 with tmux 3.3a through 3.8 on Ubuntu 24.04, with per-revision results. A push and a pull request run the oldest and newest of those releases, 3.3a and 3.8, and a release runs all of them. macOS is supported on a best-effort basis, and CI coverage for it is highly limited.
• History limit. On tmux 3.3a to 3.6 the reused initial pane keeps the global ohistory-limit. Set the server’s global value before you apply to get one history size.

Documentation¶