# Workspaces

Source: https://libtmux.org/en/ruby/latest/concepts/workspaces/

> Build pane layouts with the object API or a workspace configuration file.

A workspace arranges windows and panes for a task, such as editing code, running
a development server, and following logs. Build it with the object API when the
layout depends on program logic. Use a declarative builder when you want to
store the layout in a configuration file, such as
[tmuxp](https://tmuxp.git-pull.com/) YAML or JSON.

## Building one imperatively

Create a window, split it into panes, apply a layout, and send each pane its
command:

`Window.split()` or `Pane.split()` adds a pane. Direction and size control its
placement. `select_layout()` rearranges the panes while their processes continue
running. tmux provides `even-horizontal`, `even-vertical`, `main-horizontal`,
`main-vertical`, and `tiled` layouts.

Python's `attach=False` and C++'s detached creation keep new windows in the
background. Check the creation defaults for your port if focus matters. Splits
and resizes require tmux commands; [Control mode vs one-shot](../transports/)
covers their transport costs and batching.

## Building one declaratively

These packages read or build workspace configurations based on tmuxp:

| Port | Package | Shape |
|------|---------|-------|
| Python | tmuxp itself | the format this whole idea is named after |
| TypeScript | `@libtmux/workspace` | `applyWorkspace(server, { session_name, windows: [...] })` |
| Go | `workspace` | tmuxp-shaped, per the port's own module layout |
| Rust | `tmux-workspace` | tmuxp-shaped |
| Java | `libtmux-workspace` | "enough of tmuxp's format to describe a workspace" |
| C# | `LibTmux.Workspace` | reads tmuxp YAML directly |
| Swift | `TmuxWorkspace` | Swift, JSON, or YAML (YAML needs the `YAMLWorkspaces` trait) |

TypeScript's `applyWorkspace` applies a desired configuration. Applying the same
configuration again reuses its existing objects:

C++ provides a consumer example in `examples/workspace/` that reads tmuxp
configuration. The workspace builder is part of that example, rather than a
library package:

## Cleaning up

For temporary workspaces, Python's `Window` and `Session` context managers kill
their objects on block exit, including when the block raises:

See [Context managers](/topics/context-managers/) for cleanup support in each
port. Use explicit kill methods when the handle does not provide scope-based
cleanup.