terminal¶

Launch and manage layout-driven terminal sessions for tmux, zellij, Windows Terminal, and agent-of-empires.

Usage¶

terminal [OPTIONS] COMMAND [ARGS]...

Commands Overview¶

Hidden one-letter aliases exist, but this page uses canonical command names.

Common Layout Source Rules¶

• run, run-all, and run-aoe default to ~/dotfiles/stackops/layouts.json when --layouts-file is omitted.
• run and run-all also support --test-layout, which generates a built-in finite layout set for experimentation and cannot be combined with --layouts-file.
• --choose-layouts "" opens interactive layout selection.
• --choose-tabs "" opens interactive tab selection.
• Explicit tab selectors can be either tabName or layoutName::tabName.

run¶

Launch selected layouts from a layout configuration file.

terminal run [OPTIONS]

Examples:

# Run the default ~/dotfiles/stackops/layouts.json
terminal run

# Run only selected layouts from an explicit file
terminal run --layouts-file layouts.json --choose-layouts "dev,build"

# Run a generated test layout
terminal run --test-layout --parallel-layouts 2 --monitor

# Select tabs by name or layout-qualified name
terminal run --layouts-file layouts.json --choose-tabs "server,build::tests"

# Restart matching sessions before relaunching
terminal run --layouts-file layouts.json --on-conflict restart

run-all¶

Merge every tab from every layout into one paced run.

terminal run-all [OPTIONS]

Examples:

# Keep at most eight tabs active while working through the whole file
terminal run-all --layouts-file layouts.json --max-parallel-tabs 8

# Use the generated test layout and close finished tabs as work drains
terminal run-all --test-layout --max-parallel-tabs 6 --kill-finished-tabs

run-aoe¶

Launch selected layout tabs through agent-of-empires.

Mapping:

• layoutName -> AoE group
• tabName -> AoE title
• startDir -> AoE target path
• command -> initial prompt by default

terminal run-aoe [OPTIONS]

Examples:

# Treat each tab command as the initial prompt
terminal run-aoe --layouts-file layout.json --model <model-name> --sandbox workspace-write --yolo

# Use each tab command as an agent-command override instead
terminal run-aoe --layouts-file layout.json --tab-command-mode cmd

# Preview generated aoe commands without executing them
terminal run-aoe --layouts-file layout.json --dry-run

attach¶

Attach to a session target.

terminal attach [OPTIONS] [NAME]

Example:

# Choose a pane or tab interactively
terminal attach --window

kill¶

Kill a session target.

terminal kill [OPTIONS] [NAME]

Example:

# Choose an exact pane or tab to kill
terminal kill --window

trace¶

Trace a tmux session until every observable target matches a strict stop criterion.

terminal trace SESSION_NAME [OPTIONS]

Examples:

# Wait until every pane returns to an idle shell
terminal trace build-session

# Wait until every pane has exited
terminal trace build-session --every 5 --until all-exited

# Require successful exit codes from every pane
terminal trace build-session --until exit-code --exit-code 0

create-from-function¶

Create and immediately launch a zellij layout that runs the same script function in multiple tabs. If --function is omitted, StackOps prompts for a function; if --path is a directory, it searches for .py, .sh, and .ps1 candidates.

terminal create-from-function [OPTIONS]

Each generated tab runs:

uv run python -m fire <file> <function> --idx=<n> --idx_max=<num_process>

Example:

terminal create-from-function --num-process 4 --path ./my_script.py --function process_data

balance-load¶

Adjust a layout file to limit tabs per layout or total layout weight.

terminal balance-load LAYOUT_PATH [OPTIONS]

If --output-path is omitted, StackOps writes <stem>_adjusted_<max>_<threshold>_<method>.json beside the source file.

create-template¶

Create a starter layout file in the current directory.

terminal create-template [NAME] [OPTIONS]

Current behavior:

• The template uses the current directory to build startDir.
• The default tab command is bash on non-Windows systems and powershell on Windows.
• Existing files are not overwritten.

summarize¶

Print layout counts and per-layout tab totals.

terminal summarize LAYOUT_PATH

Current behavior:

• Prints the file path, version, total layout count, total tab count, average tabs per layout, and min/max tab counts.
• Accepts the current wrapped layout-file shape with a top-level layouts array.

Layout File Format¶

Current layout files use the LayoutsFile wrapper. The important keys are layouts, layoutName, layoutTabs, tabName, startDir, and command.

{
  "$schema": "https://bit.ly/cfglayout",
  "version": "0.1",
  "layouts": [
    {
      "layoutName": "Development",
      "layoutTabs": [
        {
          "tabName": "editor",
          "startDir": "~/projects/myapp",
          "command": "hx ."
        },
        {
          "tabName": "server",
          "startDir": "~/projects/myapp",
          "command": "python -m http.server 8000"
        }
      ]
    }
  ]
}

Older examples that use tabs or cwd are stale. The current schema uses layoutTabs and startDir.

Backend Notes¶

• run supports tmux, zellij, windows-terminal, and auto. auto resolves to zellij on non-Windows systems and windows-terminal on Windows.
• run-all supports tmux, zellij, and auto. auto resolves to zellij on non-Windows systems and is not supported on Windows.
• attach and kill support tmux, zellij, and auto. Their auto mode resolves to zellij on non-Windows systems and is rejected on Windows.
• trace is tmux-only.
• create-from-function launches through zellij.