tmuxp load¶

Load a tmux session from a workspace file — this is the command you reach for most. Point it at a project directory or a YAML/JSON file and tmuxp builds the session and attaches you to it; the flags below are for the cases where you want something other than that default.

Command¶

Load tmuxp workspace file(s) and create or attach to a tmux session.

Usage¶

usage: tmuxp load [-h] [-L socket_name] [-S socket_path] [-f tmux_config_file]
                  [-s new_session_name] [--yes] [-d] [-a] [-2 | -8]
                  [--log-file file_path] [--progress-format FORMAT]
                  [--progress-lines N] [--no-progress]
                  workspace-file [workspace-file ...]

Examples¶

$ tmuxp load myproject

$ tmuxp load ./workspace.yaml

$ tmuxp load -d myproject

$ tmuxp load -y dev staging

$ tmuxp load -L other-socket myproject

$ tmuxp load -a myproject

Positional Arguments¶

workspace_files workspace-file¶

filepath to session or filename of session in tmuxp workspace directory

Default: None
Required

Options¶

-L socket_name¶

passthru to tmux(1) -L

Default: None

-S socket_path¶

passthru to tmux(1) -S

Default: None

-f tmux_config_file¶

passthru to tmux(1) -f

Default: None

-s new_session_name¶

start new session with new session name

Default: None

--yes, -y¶

always answer yes

Default: False

-d¶

load the session without attaching it

Default: False

-a, --append¶

load workspace, appending windows to the current session

Default: False

--log-file file_path¶

file to log errors/output to

Default: None

--progress-format FORMAT¶

Spinner line format: preset name (default, minimal, window, pane, verbose) or a format string with tokens {session}, {window}, {progress}, {window_progress}, {pane_progress}, etc. Env: TMUXP_PROGRESS_FORMAT

Default: None

--progress-lines N¶

Number of script-output lines shown in the spinner panel (default: 3). 0 hides the panel entirely (script output goes to stdout). -1 shows unlimited lines (capped to terminal height). Env: TMUXP_PROGRESS_LINES

Default: None
Type: int

--no-progress¶

Disable the animated progress spinner. Env: TMUXP_PROGRESS=0

Default: False

-2¶

force tmux to assume the terminal supports 256 colours.

Default: None

-8¶

like -2, but indicates that the terminal supports 88 colours.

Default: None

Basic usage¶

You can load your tmuxp file and attach the tmux session via a few shorthands:

The directory with a .tmuxp.{yaml,yml,json} file in it
The name of the project file in your $HOME/.tmuxp folder
The direct path of the tmuxp file you want to load

Path to folder with .tmuxp.yaml, .tmuxp.yml, .tmuxp.json:

Project based

Projects with a file named .tmuxp.yaml or .tmuxp.json can be loaded:

// current directory
$ tmuxp load .

$ tmuxp load ../

$ tmuxp load path/to/folder/

$ tmuxp load /path/to/folder/

User based

Name of the config, assume $HOME/.tmuxp/myconfig.yaml:

$ tmuxp load myconfig

Direct path to json/yaml file:

$ tmuxp load ./myfile.yaml

$ tmuxp load /abs/path/to/myfile.yaml

$ tmuxp load ~/myfile.yaml

Direct

Absolute and relative directory paths are supported.

$ tmuxp load [filename]

Inside sessions¶

When you load a workspace from inside an existing tmux client, tmuxp asks what you want rather than guessing — switch to the freshly built session, append its windows to the session you’re in, or build it detached and stay put:

Already inside TMUX, switch to session? yes/no
Or (a)ppend windows in the current active session?
[y/n/a]:

Loading from inside an existing tmux client.

Options¶

All of these options can be preselected to skip the prompt:

Attach / open the client after load:
```
$ tmuxp load -y config
```
Detached / open in background:
```
$ tmuxp load -d config
```
Append windows to existing session
```
$ tmuxp load -a config
```

Loading multiple sessions¶

Multiple sessions can be loaded at once. The first ones will be created without being attached. The last one will be attached if there is no -d flag on the command line.

$ tmuxp load [filename1] [filename2] ...

Custom session name¶

A session name can be provided at the terminal. If multiple sessions are created, the last session is named from the terminal.

$ tmuxp load -s [new_session_name] [filename1] ...

Logging¶

The output of the load command can be logged to a file for debugging purposes. the log level can be controlled with the global --log-level option (defaults to INFO).

$ tmuxp load [filename] --log-file [log_filename]

$ tmuxp --log-level [LEVEL] load [filename] --log-file [log_filename]

Progress display¶

When loading a workspace, tmuxp shows an animated spinner with build progress. The spinner updates as windows and panes are created, giving real-time feedback during session builds.

Presets¶

Five built-in presets control the spinner format:

Preset	Format
`default`	`Loading workspace: {session} {bar} {progress} {window}`
`minimal`	`Loading workspace: {session} [{window_progress}]`
`window`	`Loading workspace: {session} {window_bar} {window_progress_rel}`
`pane`	`Loading workspace: {session} {pane_bar} {session_pane_progress}`
`verbose`	`Loading workspace: {session} [window {window_index} of {window_total} · pane {pane_index} of {pane_total}] {window}`

Select a preset with --progress-format:

$ tmuxp load --progress-format minimal myproject

Or via environment variable:

$ TMUXP_PROGRESS_FORMAT=verbose tmuxp load myproject

Custom format tokens¶

Use a custom format string with any of the available tokens:

Token	Description
`{session}`	Session name
`{window}`	Current window name
`{window_index}`	Current window number (1-based)
`{window_total}`	Total number of windows
`{window_progress}`	Window fraction (e.g. `1/3`)
`{window_progress_rel}`	Completed windows fraction (e.g. `1/3`)
`{windows_done}`	Number of completed windows
`{windows_remaining}`	Number of remaining windows
`{pane_index}`	Current pane number in the window
`{pane_total}`	Total panes in the current window
`{pane_progress}`	Pane fraction (e.g. `2/4`)
`{progress}`	Combined progress (e.g. `1/3 win · 2/4 pane`)
`{session_pane_progress}`	Panes completed across the session (e.g. `5/10`)
`{overall_percent}`	Pane-based completion percentage (0–100)
`{bar}`	Composite progress bar
`{pane_bar}`	Pane-based progress bar
`{window_bar}`	Window-based progress bar
`{status_icon}`	Status icon (⏸ during before_script)

Example:

$ tmuxp load --progress-format "{session} {bar} {overall_percent}%" myproject

Panel lines¶

The spinner shows script output in a panel below the spinner line. Control the panel height with --progress-lines:

Hide the panel entirely (script output goes to stdout):

$ tmuxp load --progress-lines 0 myproject

Show unlimited lines (capped to terminal height):

$ tmuxp load --progress-lines -1 myproject

Set a custom height (default is 3):

$ tmuxp load --progress-lines 5 myproject

Disabling progress¶

Disable the animated spinner entirely:

$ tmuxp load --no-progress myproject

Or via environment variable:

$ TMUXP_PROGRESS=0 tmuxp load myproject

When progress is disabled, logging flows normally to the terminal and no spinner is rendered.

Before-script behavior¶

During before_script execution, the progress bar shows a marching animation and a ⏸ status icon, indicating that tmuxp is waiting for the script to finish before continuing with pane creation.