Layouts¶

Layout schema¶

The schema lives in stackops.utils.schemas.layouts.layout_types.

Core types¶

Helper behavior¶

• serialize_layouts_to_file(layouts, version, path, write_mode="replace_file") writes a layout file with "$schema": "https://bit.ly/cfglayout" and replaces any existing file content.
• serialize_layouts_to_file(layouts, version, path, write_mode="merge_by_layout_name") preserves existing layouts, replaces layouts that share the same layoutName, and appends new layout names.
• substitute_home(tabs) expands ~ and $HOME and rewrites shorthand command prefixes:
• f ... -> ~/.config/stackops/scripts/wrap_stackops fire ...
• t ... -> ~/.config/stackops/scripts/wrap_stackops terminal ...
• s ... -> ~/.config/stackops/scripts/wrap_stackops seek ...

The current schema key is layoutTabs. There is no alternate tabs field in the typed definitions.

Building layouts from Python functions¶

stackops.cluster.sessions_managers.utils.maker converts Python functions into TabConfig entries.

Main helpers¶

make_layout_from_functions() accepts both launch styles through method:

• "script" to execute generated Python through uv
• "fire" to use the wrap_stackops fire entrypoint

Its flags parameter is passed through to the selected launch mode as either uv_run_flags or fire_flags.

Set max_stagger to add a random startup delay of up to that many seconds to each generated function tab. The extra delay is applied after the helper returns the tab command, so get_fire_tab_using_uv() and get_fire_tab_using_fire() keep their direct command behavior unchanged. Negative values raise ValueError.

Example¶

from stackops.cluster.sessions_managers.tmux.tmux_local import run_tmux_layout
from stackops.cluster.sessions_managers.utils.maker import make_layout_from_functions


def ingest() -> None:
    print("ingest")


def train() -> None:
    print("train")


layout = make_layout_from_functions(
    functions=[ingest, train],
    functions_weights=[1, 2],
    import_module=True,
    tab_configs=[],
    layout_name="ml-workflow",
    method="script",
    uv_with=["stackops"],
    uv_project_dir=None,
    flags="",
    start_dir="~/code/my-project",
    max_stagger=10.0,
)

run_tmux_layout(layout_config=layout, on_conflict="rename")

If functions_weights is None, each function is treated as weight 1.

Controlling layout size¶

stackops.cluster.sessions_managers.utils.load_balancer provides two controls.

limit_tab_num()¶

limit_tab_num(
    layout_configs=layouts,
    max_thresh=8,
    threshold_type="number",
    breaking_method="moreLayouts",
)

Supported threshold_type values:

• "number" for raw tab count
• "weight" for summed tabWeight

Supported breaking_method values:

• "moreLayouts"
• "combineTabs"

limit_tab_weight()¶

limit_tab_weight(layout_configs, max_weight, command_splitter) rewrites overweight tabs by calling your command_splitter(command, to=max_weight) function and replacing the original tab with ..._part1, ..._part2, and so on.

Convenience launcher¶

1. starts all sessions with a 2-second poll window
2. runs the monitoring routine at 2-second intervals
3. kills all managed sessions when monitoring finishes

Backend-specific layout generators¶

The same LayoutConfig can be handed to the tmux backend:

• run_tmux_layout(layout_config, on_conflict) using exit_mode="backToShell"

The generator class is:

• TmuxLayoutGenerator

That class is responsible for rendering backend-specific layout artifacts:

• tmux shell scripts

API reference¶

Layout schema¶

Layout builders¶

Layout load balancer¶

Load balancer helper¶

split_tabs_by_weight(
    tabs: list[TabConfig], max_weight: int
) -> list[list[TabConfig]]

combine_tabs_into_super_tabs(
    tabs: list[TabConfig], num_super_tabs: int
) -> list[TabConfig]

combine_tabs_by_weight_into_super_tabs(
    tabs: list[TabConfig], max_weight: int
) -> list[TabConfig]

restrict_num_tabs_helper1(
    layout_configs: list[LayoutConfig],
    max_thresh: int,
    threshold_type: Literal["number"],
    breaking_method: Literal["moreLayouts"],
) -> list[LayoutConfig]

restrict_num_tabs_helper2(
    layout_configs: list[LayoutConfig],
    max_thresh: int,
    threshold_type: Literal["number"],
    breaking_method: Literal["combineTabs"],
) -> list[LayoutConfig]

restrict_num_tabs_helper3(
    layout_configs: list[LayoutConfig],
    max_thresh: int,
    threshold_type: Literal["weight"],
    breaking_method: Literal["moreLayouts"],
) -> list[LayoutConfig]

restrict_num_tabs_helper4(
    layout_configs: list[LayoutConfig],
    max_thresh: int,
    threshold_type: Literal["weight"],
    breaking_method: Literal["combineTabs"],
) -> list[LayoutConfig]

options:
  show_root_heading: true
  show_source: false
  members_order: source


options:
  show_root_heading: true
  show_source: false
  members_order: source


options:
  show_root_heading: true
  show_source: false
  members_order: source


options:
  show_root_heading: true
  show_source: false
  members_order: source


options:
  show_root_heading: true
  show_source: false
  members_order: source


options:
  show_root_heading: true
  show_source: false
  members_order: source

tmux layout helpers¶

tmux common helpers¶

tmux execution helpers¶

tmux layout helpers¶

tmux status helpers¶