Save a running session

Sometimes the workspace comes first and the profile second. You split a window here, drag a border there, rename a pane, and twenty minutes later you have a layout that is exactly right and lives nowhere but in a tmux server that will not survive the next reboot. glaze save writes that session into a profile. It captures the structure, and only the structure. The rest you add by hand, and this page is honest about why.

The flag reference is on glaze save.

Step 1: arrange the session#

1. Build the session in tmux. Split, resize and move the panes until the layout is correct.
2. Name each window that you want to keep: tmux rename-window ice-breaker.
3. Name each pane that you want to keep: tmux select-pane -T breach-protocol.
4. Select the window and the pane that up must focus.

A window that tmux names after its program (automatic-rename) gets a different name on each run, so save writes no name for it. A pane title that is the host name is tmux’s default title, so save writes no name for it either. Name the parts that matter to you.

Step 2: preview the profile#

Run save with --stdout inside the session. Nothing is written:

$ glaze save --stdout
session {
  name               = "daemon-run"
  starting_directory = "/home/v/runs/arasaka"

  window {
    name   = "ice-breaker"
    layout = "8205,80x24,0,0{40x24,0,0,0,39x24,41,0,1}"
    focus  = true

    pane {
      name               = "breach-protocol"
      starting_directory = "/home/v/runs/arasaka"
    }

    pane {
      starting_directory = "/home/v/runs/arasaka/payloads"
      focus              = true
    }
  }

  window {
    name   = "netwatch"
    layout = "b25f,80x24,0,0,2"

    pane {
      starting_directory = "/home/v/runs/arasaka"
      focus              = true
    }
  }
}

Only the profile goes to stdout. The log lines go to stderr, so glaze save --stdout > saved.glaze writes a clean file.

Outside a pane of the target tmux server, name the session with --session daemon-run.

Step 3: write the file#

$ glaze save                                                  # write ./.glaze
$ glaze save --profile-path ./daemon-run.glaze                # write a named file

save does not replace an existing file:

$ glaze save
could not save to `.glaze`: file exists; use --force to replace it

$ glaze save --force

With --force, save writes the same way as format: through a temporary file, through a symlink and with the permissions of the old file. Thus a failed write keeps the old profile.

Step 4: finish the profile by hand#

A saved profile is a scaffold. It recreates your layout and nothing else. To finish it:

1. Add commands to each pane that runs a program. See Commands.
2. Add envs to the session for the environment variables that the panes need. See Environment.
3. Add options and hooks where you need them. See Hooks and options.
4. Replace each raw layout string with a preset if you want a readable profile: even-horizontal, even-vertical, main-horizontal, main-vertical or tiled.
5. Replace an absolute starting_directory with a relative path if you share the profile. A relative path is relative to the directory of the profile.
6. Run glaze format --validate to check the result before the first glaze up.

What save captures#

Why save refuses the interesting parts#

I would love to tell you save round-trips a whole session. It does not, and that is a decision, not a gap on the roadmap.

The problem is provenance. tmux can tell glaze what a session looks like now. It cannot tell glaze who put it there. show-environment returns the entire session environment, which is your shell’s environment plus whatever you exported since: tokens, keys, the lot. Exporting that writes secrets into a file that you will commit, because of course you will. show-options returns the effective state, which mixes your tmux.conf, your manual tweaks and the handful of values glaze set, so replaying it re-asserts your whole global config as session options. And a command or a hook is code. tmux cannot report what a pane is running, only the name of its foreground process, and anything glaze did capture would run again on every glaze up, including that destructive one-off you ran in a forgotten pane last Tuesday.

So save captures the inert parts and leaves the rest to you. It is a little more typing. It is also the only version of this feature that cannot hurt you.

About the layout string#

tmux reports a window layout as a coordinate string, for example 8205,80x24,0,0{40x24,0,0,0,39x24,41,0,1}, not as a preset. save writes that string verbatim and up replays it verbatim, so your pane geometry comes back exactly. The rules:

• Glazier validates the structure of the string when it parses the profile. A malformed string causes an error.
• tmux recomputes the leading checksum. If you edit the geometry by hand and make an error, tmux rejects the layout when up runs.
• The string must describe as many panes as the window declares.
• A raw string fixes the size of every pane. Glazier ignores size and adjust in that window and shows a warning.
• tmux 3.9 and later print a layout as JSON, and save writes the form that your tmux prints. A JSON layout needs tmux 3.9 or later. To share the profile with users of an older tmux, replace it with a preset.

The string is exact but not easy to read. For a profile that you edit by hand, a preset is the better choice. See Window.