# libtmux.workspace

**Workspace Manager concept example** A working example of the core library. It can change without notice.

- **Package:** libtmux/workspace
- **Language:** Common Lisp
- **Kind:** module
- **Source:** https://github.com/libtmux/libtmux-lisp/blob/c2e5fc4ed3befda21f45dfa5d5868c38fd138311/src/workspace.lisp#L1
- **Page:** https://libtmux.org/en/lisp/latest/workspace/reference/libtmux-workspace/

Owned Common Lisp workspace descriptions and explicit tmux application.
MAKE-WORKSPACE validates inert native data without evaluation. PLAN-WORKSPACE
is local and pure; APPLY-WORKSPACE is the explicit external-operation boundary.
Workspace objects, plans, steps, results, and their readers return defensive
data. Conflicts fail before mutation, and partial application retains evidence.

## Members

### Common operations

- [`apply-workspace`](/en/lisp/latest/workspace/reference/libtmux-workspace-apply-workspace/) (function): Create or reuse WORKSPACE through explicit CLIENT and return WORKSPACE-RESULT.
The function first calls FETCH-SNAPSHOT and PLAN-WORKSPACE. A proven match
returns immediately with no command outcomes. A missing session executes each
planned core mutation once, in order, then captures and proves the final
topology. TIMEOUT and OUTPUT-LIMIT, when supplied, apply separately to each core
operation; CANCEL-TOKEN is shared. Conflicts dispatch no mutation.
- [`make-workspace`](/en/lisp/latest/workspace/reference/libtmux-workspace-make-workspace/) (function): Validate closed native DATA and return an owned WORKSPACE without I/O.
DATA is a keyword plist in schema libtmux.lisp.workspace/1. Lists and vectors
must be finite. MAX-WINDOWS, MAX-PANES, and MAX-ARGV bound retained topology and
commands. MAX-ENVIRONMENT bounds session (name . value) string pairs; tmux
stores them in the session environment inherited by later panes. Pane :COMMAND
is argv; :SHELL-COMMAND is explicit shell source, mutually exclusive with argv.
Window :LAYOUT is a named keyword or (:CUSTOM string) validated by tmux on apply.
Names reject characters tmux would rewrite. Unknown/duplicate keys, invalid
types or limits signal INVALID-WORKSPACE. Mutable inputs are copied.
- [`parse-workspace`](/en/lisp/latest/workspace/reference/libtmux-workspace-parse-workspace/) (function): Parse one bounded libtmux.lisp.workspace/1 JSON string into a WORKSPACE.
The complete document uses a closed grammar, rejects duplicate members, and
never interns or evaluates external names. Limits bound UTF-8 bytes, nesting,
nodes, strings, windows, total panes, argv length, session environment pairs
(MAX-ENVIRONMENT, default 256), and integer token digits. Pane shell_command is
explicit shell source; window layout accepts a named string or a custom object.
Input and retained values are copied. Signals INVALID-WORKSPACE-DOCUMENT or
WORKSPACE-LIMIT-EXCEEDED with WORKSPACE-PATH and WORKSPACE-LIMIT diagnostics.
- [`plan-steps`](/en/lisp/latest/workspace/reference/libtmux-workspace-plan-steps/) (function): Return PLAN's ordered steps as a fresh simple vector. No I/O.
- [`plan-workspace`](/en/lisp/latest/workspace/reference/libtmux-workspace-plan-workspace/) (function): Return a finite local WORKSPACE-PLAN, optionally against captured SNAPSHOT.
Without SNAPSHOT, return the deterministic creation plan. With SNAPSHOT, return
that plan when the named session is absent, an empty proven no-op when topology
matches, or signal WORKSPACE-CONFLICT before dispatch. Planning compares window
names, declared indexes, and pane counts; creation-only cwd, argv, and layout
are not inferred from mutable live state. Explicit indexes are reserved before
automatic windows. Pane creation and final order follow the declaration. No
tmux I/O occurs.
- [`read-workspace`](/en/lisp/latest/workspace/reference/libtmux-workspace-read-workspace/) (function): Read one bounded regular UTF-8 JSON file and return an owned WORKSPACE.
PATH is opened for input and never modified. MAX-INPUT-BYTES is enforced on
bytes read even if the file changes after opening. The descriptor is opened
nonblocking, then directories and special files are rejected before reading.
Other OPTIONS are forwarded to PARSE-WORKSPACE. Signals
INVALID-WORKSPACE-DOCUMENT or WORKSPACE-LIMIT-EXCEEDED and closes the stream.
- [`result-created-p`](/en/lisp/latest/workspace/reference/libtmux-workspace-result-created-p/) (function): Return true when APPLY-WORKSPACE created the declared session.
- [`result-outcomes`](/en/lisp/latest/workspace/reference/libtmux-workspace-result-outcomes/) (function): Return retained COMMAND-OUTCOME objects in a fresh simple vector.
- [`result-snapshot`](/en/lisp/latest/workspace/reference/libtmux-workspace-result-snapshot/) (function): Return the final captured SNAPSHOT retained by RESULT. No I/O.
- [`step-action`](/en/lisp/latest/workspace/reference/libtmux-workspace-step-action/) (function): Return STEP's action keyword, without I/O.
- [`step-data`](/en/lisp/latest/workspace/reference/libtmux-workspace-step-data/) (function): Return a fresh plist of STEP operands, without I/O.
- [`workspace-apply-failed`](/en/lisp/latest/workspace/reference/libtmux-workspace-workspace-apply-failed/) (exception): Workspace application stopped with retained partial outcomes.
- [`workspace-conflict`](/en/lisp/latest/workspace/reference/libtmux-workspace-workspace-conflict/) (exception): Captured topology conflicts with the declared workspace.
- [`workspace-deadline-exceeded`](/en/lisp/latest/workspace/reference/libtmux-workspace-workspace-deadline-exceeded/) (exception): The application budget expired at a workspace boundary.
WORKSPACE-LIMIT returns :TOTAL-TIMEOUT. No new command outcome is implied;
previous completed outcomes remain on a wrapping WORKSPACE-APPLY-FAILED.
An already admitted core call retains its own timeout and cleanup contract.

### Other members

- [`failed-step`](/en/lisp/latest/workspace/reference/libtmux-workspace-failed-step/) (function): Return the failed or refused next WORKSPACE-STEP, or NIL for final verification.
NIL does not imply that no mutations completed; inspect RESULT-OUTCOMES.
- [`invalid-workspace`](/en/lisp/latest/workspace/reference/libtmux-workspace-invalid-workspace/) (exception): Native workspace data violates the closed workspace grammar.
- [`invalid-workspace-document`](/en/lisp/latest/workspace/reference/libtmux-workspace-invalid-workspace-document/) (exception): A workspace JSON document is malformed, unknown, or invalid.
- [`workspace`](/en/lisp/latest/workspace/reference/libtmux-workspace-workspace/) (class): An immutable-by-contract, owned workspace description.
- [`workspace-data`](/en/lisp/latest/workspace/reference/libtmux-workspace-workspace-data/) (function): Return fresh closed native data for WORKSPACE, without I/O.
- [`workspace-error`](/en/lisp/latest/workspace/reference/libtmux-workspace-workspace-error/) (exception): A workspace validation, planning, or application failure.
- [`workspace-limit`](/en/lisp/latest/workspace/reference/libtmux-workspace-workspace-limit/) (function): Return the exhausted workspace limit name, or NIL, without I/O.
- [`workspace-limit-exceeded`](/en/lisp/latest/workspace/reference/libtmux-workspace-workspace-limit-exceeded/) (exception): A workspace JSON or file input exceeds a configured bound.
- [`workspace-path`](/en/lisp/latest/workspace/reference/libtmux-workspace-workspace-path/) (function): Return a fresh vector locating the workspace error, without I/O.
- [`workspace-plan`](/en/lisp/latest/workspace/reference/libtmux-workspace-workspace-plan/) (class): A finite local plan; an empty step vector is a proven no-op.
- [`workspace-result`](/en/lisp/latest/workspace/reference/libtmux-workspace-workspace-result/) (class): Retained workspace application evidence and final captured topology.
- [`workspace-step`](/en/lisp/latest/workspace/reference/libtmux-workspace-workspace-step/) (class): One inspectable, inert workspace operation in execution order.