Layouts¶

The layout APIs turn Python intent into terminal structure. They define tabs, serialize layouts, build tab commands from callables, and split oversized layouts before handing them to zellij, tmux, or Windows Terminal backends.

Layout schema¶

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

Core types¶

Helper behavior¶

• serialize_layouts_to_file(layouts, version, path) writes a new layout file with "$schema": "https://bit.ly/cfglayout".
• If the target file already exists, serialize_layouts_to_file() replaces layouts that share the same layoutName and appends new ones.
• 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 callables 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.

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",
)

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¶

load_balancer.run(layouts, on_conflict) is a thin helper that:

1. creates a ZellijLocalManager
2. starts all sessions
3. runs the monitoring routine
4. kills all managed sessions when monitoring finishes

Backend-specific layout generators¶

The same LayoutConfig can be handed to multiple backends:

• run_zellij_layout(layout_config, on_conflict)
• run_tmux_layout(layout_config, on_conflict)
• run_wt_layout(layout_config, exit_mode)

Their generator classes are:

• ZellijLayoutGenerator
• TmuxLayoutGenerator
• WTLayoutGenerator

Those classes are responsible for rendering backend-specific layout artifacts:

• zellij KDL files
• tmux shell scripts
• Windows Terminal PowerShell scripts

API reference¶

Layout schema¶

serialize_layouts_to_file(
    layouts: list[LayoutConfig],
    version: Literal["0.1"],
    path: str,
)

Layout builders¶

Layout load balancer¶

Zellij layout helpers¶

ZellijLayoutGenerator(
    layout_config: LayoutConfig, session_name: str
)

create_layout_file() -> bool

restart_tab(tab_name: str) -> bool

create_zellij_layout(
    layout_config: LayoutConfig, layout_template: str
) -> str

tmux layout helpers¶

Windows Terminal layout helpers¶

WTLayoutGenerator(
    layout_config: LayoutConfig,
    session_name: str,
    exit_mode: SessionExitMode,
)

create_layout_file() -> bool

get_wt_layout_preview(layout_config: LayoutConfig) -> str

get_status_report() -> dict[str, Any]

print_status_report() -> None

run_wt_layout(
    layout_config: LayoutConfig, exit_mode: SessionExitMode
) -> None

run_command_in_wt_tab(
    command: str, tab_name: str, cwd: str | None
) -> str