Skip to content
ck3mp3rPublic

About

Flexbox-inspired layout and session manager for tmux, with experimental rex, herdr and zellij backends. Complex sessions from YAML. πŸ‰

Topics

Resources

Stars

42 stars

Watchers

1 watching

Forks

Latest commit

Β 

History

1,076 Commits

Folders and files

Repository files navigation

A simple, flexbox-inspired layout and session manager for tmux, with experimental zellij, herdr, and rex support. Define complex multi-window, multi-pane layouts in YAML and manage session lifecycles with startup/shutdown hooks.

Full Documentation

Features

  • Flexbox-inspired layouts - Define pane splits with flex and flex_direction (row/column)
  • Template variables - Dynamic configurations with Tera template support and array variables
  • Session lifecycle management - Startup/shutdown commands and embedded scripts
  • Dual configuration modes - Global configs (~/.config/laio) or local project configs (.laio.yaml)
  • Session serialization - Export existing tmux, zellij, herdr, and rex sessions to YAML format
  • Focus & zoom control - Pin focus and zoom states in configuration
  • Environment & shell customization - Per-session env vars and shell overrides
  • Multiplexer support - tmux native; experimental Zellij, herdr, and rex backends, selectable via --muxer or LAIO_MUXER. On herdr, each laio config runs as a workspace in the dedicated laio session. On rex, each laio config runs as one rex session named after the config: laio recognizes its rex sessions by the sidecar store, so labels are plain names.

Quick Start

# Install (see Installation section)
nix profile install "github:ck3mp3r/laio-cli"

# Create a new config
laio config create myproject

# Start the session
laio start myproject

# List sessions and configs
laio list

Installation

Supported platforms:

  • Linux: x86_64 (Intel/AMD), aarch64 (ARM)
  • macOS: aarch64 (Apple Silicon)

Nix

built with nix

nix profile install "github:ck3mp3r/laio-cli"

Homebrew

brew tap ck3mp3r/laio-cli https://github.com/ck3mp3r/laio-cli/
brew install laio

Binary Download

Download from the Release Page and add to PATH.

Development

Prerequisites

  • Rust 1.85+ (edition 2024; or use Nix for reproducible builds)
  • tmux 3.0+

Build

cargo build --release
# Binary at: target/release/laio

Test

cargo nextest run

Development Environment (Nix)

nix develop
# or use direnv
direnv allow

Configuration Schema

The YAML configuration schema is defined in src/common/config/schema.json. Use this for editor integration (LSP, validation).

Usage

Commands

laio start [name]                  # Start session (interactive picker if name omitted)
laio start --file config.yaml      # Start from specific file
laio start --var key=value         # Start with template variables
laio start --muxer herdr           # Start with herdr (experimental)
laio start --muxer rex             # Start with rex (experimental)
laio stop [name]                   # Stop session
laio stop --all                    # Stop all laio-managed sessions
laio list                          # List sessions and configs
laio config create <name>          # Create new config
laio config create --var key=value # Create from _default.yaml with variables
laio config create --copy src      # Create from existing config
laio config edit <name>            # Edit config in $EDITOR
laio config link <name>            # Symlink .laio.yaml to global config
laio session yaml                  # Export current tmux, zellij, herdr, or rex session to YAML
laio completion <shell>            # Generate shell completions

See laio --help or full documentation for all options.

Template Variables

Create reusable configurations with template variables:

name: {{ session_name }}
path: {{ path }}

windows:
{% for service in services %}
  - name: {{ service }}
    panes:
      - path: ./{{ service }}
        commands:
          - command: npm
            args: [run, dev]
{% endfor %}

Auto-injected variables:

  • session_name - Set from the session name (cannot be overridden)
  • path - Defaults to current working directory

Start with variables:

# Uses session name and cwd automatically
laio start myproject

# Override path
laio start myproject --var path=~/projects/myproject

# Multiple services (array variables)
laio start microservices \
  --var services=auth \
  --var services=api \
  --var services=frontend

# Or use inline CSV syntax with key[]=
laio start microservices --var 'services[]=auth,api,frontend'

# Escaped comma for literal commas in values
laio start myapp --var 'features[]=auth\,sso,logging,metrics'

See template variable docs for complete syntax and examples.

Configuration

Configurations are YAML files defining session layouts:

name: myproject
path: /path/to/myproject

# Session lifecycle hooks
startup:
  - command: docker-compose
    args: [up, -d]

startup_script: |
  #!/usr/bin/env bash
  echo "Session starting..."

shutdown:
  - command: docker-compose
    args: [down]

shutdown_script: |
  #!/usr/bin/env bash
  echo "Cleaning up..."

# Session environment
shell: /bin/zsh
env:
  NODE_ENV: development
  DEBUG: "app:*"

# Window and pane layout
windows:
  - name: editor
    focus: true  # active window after session creation
    panes:
      - name: nvim
        commands:
          - command: $EDITOR

  - name: dev
    flex_direction: row  # vertical split (panes side-by-side)
    panes:
      - flex: 2
        flex_direction: column  # horizontal split (panes stacked)
        panes:
          - flex: 3
            path: ./src
            focus: true  # initial focus
            commands:
              - command: npm
                args: [run, dev]
          - flex: 1
            zoom: true  # start zoomed
            script: |
              #!/usr/bin/env bash
              tail -f logs/app.log
      - flex: 1
        style: bg=blue,fg=white  # tmux pane styling

Key features:

  • flex: Proportional sizing (e.g., flex: 2 = twice the size of flex: 1)
  • flex_direction: row (vertical split, side-by-side) or column (horizontal split, stacked)
  • focus (window): Active window after session creation
  • focus (pane): Pin initial cursor position within a window
  • zoom: Start pane in zoomed state
  • commands: Sequential command execution
  • script: Inline script blocks
  • path: Working directory (absolute or relative to session root)

See configuration docs for all options.

Project Configurations

Create .laio.yaml in any project directory:

cd myproject
laio config create  # creates .laio.yaml
laio start          # auto-detects and uses .laio.yaml

Link local configs to global namespace:

laio config link myproject  # symlinks .laio.yaml -> ~/.config/laio/myproject.yaml

Session Serialization

Export existing tmux, zellij, herdr, and rex sessions to YAML:

# From within a tmux, zellij, herdr, or rex session
laio session yaml > ~/.config/laio/newsession.yaml

Experimental rex Backend

Select rex with --muxer rex or LAIO_MUXER=rex. Each laio config runs as one rex session named after the config: laio recognizes its rex sessions by the sidecar store, so labels are plain names.

  • Attach runs rex do session.select session_id=session:<id>. Remote Control must be enabled in Rex.app under Settings > Rex Server. When the attach fails, the start still succeeds and rex's error is logged as a warning.
  • Session records live in a sidecar store: LAIO_STATE_DIR when set (used as-is), otherwise $XDG_STATE_HOME/laio/rex, otherwise ~/.local/state/laio/rex.
  • Limitations: env and pane style are ignored. laio session yaml loses pane commands and ignores floating layers.

Usage Restrictions

Use of this software is strictly prohibited for any organization, company, or government directly or indirectly involved in aiding or abetting the genocide and atrocities committed against the Palestinian people in Gaza. Only individuals and entities unaffiliated with such actions are permitted to use the software.

License

See LICENSE.md

About

Flexbox-inspired layout and session manager for tmux, with experimental rex, herdr and zellij backends. Complex sessions from YAML. πŸ‰

Topics

Resources

Stars

42 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages