Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,18 @@ src/ test/
responses.rs
socket.rs
switch_test.rs
rex/ rex/
mod.rs client_test.rs
export_test.rs
layout_test.rs
mux_test.rs
mux_test/
session.rs
start.rs
stop.rs
switch.rs
session_get_test.rs
store_test.rs
tmux/ tmux/
mod.rs test/
client.rs
Expand Down
2 changes: 1 addition & 1 deletion Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "laio"
version = "0.18.0"
version = "0.19.0"
edition = "2024"
description = "A simple flexbox-like layout manager for tmux."
homepage = "https://github.com/ck3mp3r/laio-cli"
Expand Down
21 changes: 15 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[<img src="./media/laio.svg" width="450" />](https://laio.sh)

A simple, flexbox-inspired layout and session manager for tmux, with experimental zellij and herdr support. Define complex multi-window, multi-pane layouts in YAML and manage session lifecycles with startup/shutdown hooks.
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](https://laio.sh/docs/getting-started/installing)**

Expand All @@ -10,10 +10,10 @@ A simple, flexbox-inspired layout and session manager for tmux, with experimenta
- **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, and herdr sessions to YAML format
- **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 and herdr backends, selectable via `--muxer` or `LAIO_MUXER`. On herdr, each laio config runs as a workspace in the dedicated `laio` session.
- **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

Expand Down Expand Up @@ -96,6 +96,7 @@ laio start [name] # Start session (interactive picker if name o
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
Expand All @@ -104,7 +105,7 @@ 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, or herdr session to YAML
laio session yaml # Export current tmux, zellij, herdr, or rex session to YAML
laio completion <shell> # Generate shell completions
```

Expand Down Expand Up @@ -248,13 +249,21 @@ laio config link myproject # symlinks .laio.yaml -> ~/.config/laio/myproject.ya

## Session Serialization

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

```bash
# From within a tmux, zellij, or herdr session
# 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.
Expand Down
8 changes: 6 additions & 2 deletions docs/content/_index.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
+++
title = "laio - a simple, flexbox-inspired layout & session manager for tmux, zellij & herdr."
title = "laio - a simple, flexbox-inspired layout & session manager for tmux, zellij, herdr & rex."
description = "Welcome to laio."
sort_by = "weight"
weight = 1
Expand Down Expand Up @@ -34,7 +34,11 @@ content = 'Use global configs (~/.config/laio) or project-local .laio.yaml files

[[extra.list]]
title = "Session Export"
content = 'Serialize existing tmux, zellij, and herdr sessions to YAML format for sharing and templating.'
content = 'Serialize existing tmux, zellij, herdr, and rex sessions to YAML format for sharing and templating.'

[[extra.list]]
title = "Multi-Muxer"
content = 'Four backends — tmux, zellij*, herdr*, and rex* — with identical YAML workflows; * experimental, see the docs for per-backend details.'

[[extra.list]]
title = "Supported Platforms"
Expand Down
8 changes: 6 additions & 2 deletions docs/content/docs/configuration/lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ Pane scripts run **after** pane commands complete.

## Pane Command Execution

On tmux, pane commands are batched into a single `send-keys` invocation. On zellij, all pane commands plus the pane script run in one shell invocation: the pane node gets `command="<shell>"` with a child `args` node containing `-c` and the joined commands (`<cmd1>; <cmd2>`), plus `close_on_exit true` and `start_suspended false`. The wrapper shell resolves from the session `shell`, then the login shell, then `$SHELL`, then `sh`. On herdr, each command is sent to the pane individually.
On tmux, pane commands are batched into a single `send-keys` invocation. On zellij, all pane commands plus the pane script run in one shell invocation: the pane node gets `command="<shell>"` with a child `args` node containing `-c` and the joined commands (`<cmd1>; <cmd2>`), plus `close_on_exit true` and `start_suspended false`. The wrapper shell resolves from the session `shell`, then the login shell, then `$SHELL`, then `sh`. On herdr, each command is sent to the pane individually. On rex, each pane's commands and its script are joined and sent to the pane's block in one go.

```yaml
windows:
Expand Down Expand Up @@ -184,7 +184,11 @@ windows:
- Only affects pane-level commands (not startup/shutdown commands)
- No effect on zellij, which runs all pane commands in one shell invocation (`pane_cmd_delay` is ignored)

**Note:** On tmux the delay is applied once after all panes are created. On herdr it is applied once before the first pane command is sent. On zellij `pane_cmd_delay` is ignored.
**Note:** On tmux the delay is applied once after all panes are created. On herdr it is applied once before the first pane command is sent. On rex it is applied once before the first pane command is sent. On zellij `pane_cmd_delay` is ignored.

### rex (experimental)

rex runs the whole session in one rex session named after the config: laio recognizes its rex sessions by the sidecar store, so labels are plain names. Lifecycle hooks run in the session path, without the session `env`: rex has no environment store, so `env` is ignored. Pane `style` is ignored as well. Attach runs bare `rex do session.select session_id=<full session:-prefixed id>`; Remote Control must be enabled in Rex.app under Settings > Rex Server, and a failing attach only logs a warning, so the start still succeeds. Session records live in `LAIO_STATE_DIR` when set, otherwise `$XDG_STATE_HOME/laio/rex`, otherwise `~/.local/state/laio/rex`. `laio session yaml` loses pane commands and ignores floating layers.

## Common Patterns

Expand Down
21 changes: 18 additions & 3 deletions docs/content/docs/configuration/yaml-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,10 @@ top = false
### Required Fields

**`name`** (string)
- Session name used by the multiplexer (the workspace label on herdr)
- Session name used by the multiplexer (the workspace label on herdr, the session label on rex)
- Must be unique across all sessions
- On herdr, the name must be 1-64 bytes of letters, digits, `.`, `_`, or `-`; anything else fails with "Invalid herdr session name"
- On rex, the name must be non-empty; an empty name fails with "Invalid rex session name". A name longer than 128 bytes fails as well
- tmux and zellij do not apply this restriction
- Example: `"myproject"`

Expand All @@ -40,6 +41,7 @@ top = false
- On tmux, laio sets the session's `default-shell` option to this value
- On zellij, laio uses the session `shell`, then the login shell, then `$SHELL`, then `sh`
- Ignored on herdr, which uses the shell herdr starts
- On rex, laio sets the shell of every block to this value; without it the block uses rex's default shell
- Example: `"/bin/zsh"`, `"/bin/bash"`

**`pane_cmd_delay`** (number, milliseconds)
Expand All @@ -51,10 +53,12 @@ top = false
- Example: `500` (wait 500ms)
- Recommended value for Nushell: `500`
- Not applied on zellij, where `pane_cmd_delay` has no effect
- Applied once before the first pane command on rex

**`env`** (object)
- Environment variables as key-value pairs
- Available to all commands in the session
- Ignored on rex, which has no environment store
- Example:
```yaml
env:
Expand Down Expand Up @@ -534,9 +538,9 @@ done
- Format: comma-separated key=value pairs
- Example: `"bg=blue,fg=white"`, `"bg=darkred,fg=default"`
- See `man tmux` for available style options
- Ignored on zellij and herdr, which have no pane style equivalent
- Ignored on zellij, herdr, and rex, which have no pane style equivalent

**Note:** On herdr, each laio config runs as a workspace in the dedicated `laio` session.
**Note:** 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.

**`flex_direction`** (string: `"row"` or `"column"`)
- Layout direction for nested panes
Expand All @@ -563,6 +567,17 @@ done
tail -f app.log
```

## rex (experimental)

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.

- `env` and pane `style` are ignored.
- A session with no windows fails with `Session '<name>' has no windows`; each window is capped at 24 blocks and a split depth of 16.
- `pane_cmd_delay` is applied once before the first pane command.
- Attach runs `rex do session.select session_id=<full session:-prefixed 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 `LAIO_STATE_DIR` when set, otherwise `$XDG_STATE_HOME/laio/rex`, otherwise `~/.local/state/laio/rex`.
- `laio session yaml` loses pane commands and ignores floating layers.

## Command Structure

Commands can be defined in two formats:
Expand Down
4 changes: 3 additions & 1 deletion docs/content/docs/getting-started/quick-start.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,9 @@ laio config create myproject
laio start myproject
```

> laio targets **tmux** by default. Experimental `zellij` and `herdr` backends are available via `--muxer zellij|herdr` or `LAIO_MUXER` on any command.
> laio targets **tmux** by default. Experimental `zellij`, `herdr`, and `rex` backends are available via `--muxer zellij|herdr|rex` or `LAIO_MUXER` on any command.
>
> rex runs one rex session per config, named after the config; laio recognizes its rex sessions by the sidecar store, so labels are plain names. Attach needs Remote Control 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. `env` and pane `style` are ignored, and `laio session yaml` loses pane commands and ignores floating layers. Session records live in `LAIO_STATE_DIR` when set, otherwise `$XDG_STATE_HOME/laio/rex`, otherwise `~/.local/state/laio/rex`.

This creates a default configuration with:
- An editor window that runs `{% raw %}{{ editor | default(value="nvim") }}{% endraw %}` from the template (override with `--var editor=<cmd>`)
Expand Down
34 changes: 26 additions & 8 deletions docs/content/docs/reference/cli-commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ laio start [OPTIONS] [NAME]

```
-f, --file <PATH> Use specific configuration file
-m, --muxer <MUXER> Multiplexer to use (tmux, zellij, or herdr)
-m, --muxer <MUXER> Multiplexer to use (tmux, zellij, herdr, or rex)
-p, --show-picker Show config picker (skip .laio.yaml)
--skip-cmds Skip startup commands/scripts
--skip-attach Start session without attaching
Expand Down Expand Up @@ -143,7 +143,7 @@ laio stop [OPTIONS] [NAME]
### Options

```
-m, --muxer <MUXER> Multiplexer to use (tmux, zellij, or herdr)
-m, --muxer <MUXER> Multiplexer to use (tmux, zellij, herdr, or rex)
--skip-cmds Skip shutdown commands/scripts
-a, --all Stop all laio-managed sessions
-o, --others Stop all sessions except current
Expand Down Expand Up @@ -205,7 +205,7 @@ Alias: `laio ls`
### Options

```
-m, --muxer <MUXER> Multiplexer to use (tmux, zellij, or herdr)
-m, --muxer <MUXER> Multiplexer to use (tmux, zellij, herdr, or rex)
-j, --json Output as JSON
```

Expand Down Expand Up @@ -480,7 +480,7 @@ Alias: `laio config ls`
#### Options

```
-m, --muxer <MUXER> Multiplexer to use (tmux, zellij, or herdr)
-m, --muxer <MUXER> Multiplexer to use (tmux, zellij, herdr, or rex)
-j, --json Output as JSON
```

Expand Down Expand Up @@ -516,7 +516,7 @@ Alias: `laio session ls`
#### Options

```
-m, --muxer <MUXER> Multiplexer to use (tmux, zellij, or herdr)
-m, --muxer <MUXER> Multiplexer to use (tmux, zellij, herdr, or rex)
-j, --json Output as JSON
```

Expand All @@ -543,7 +543,7 @@ laio session yaml [OPTIONS]
#### Options

```
-m, --muxer <MUXER> Multiplexer to use (tmux, zellij, or herdr)
-m, --muxer <MUXER> Multiplexer to use (tmux, zellij, herdr, or rex)
```

#### Examples
Expand All @@ -559,7 +559,7 @@ laio session yaml > ~/.config/laio/newsession.yaml
laio session yaml > .laio.yaml
```

**Note:** Must be run from within a tmux, zellij, or herdr session.
**Note:** Must be run from within a tmux, zellij, herdr, or rex session.

## laio completion

Expand Down Expand Up @@ -610,6 +610,7 @@ Override the default multiplexer.
export LAIO_MUXER=tmux # Use tmux (default)
export LAIO_MUXER=zellij # Use zellij (experimental)
export LAIO_MUXER=herdr # Use herdr (experimental)
export LAIO_MUXER=rex # Use rex (experimental)
```

Equivalent to using `--muxer` flag on every command.
Expand Down Expand Up @@ -643,7 +644,7 @@ There are practical limits to nesting depth. Very deep nesting (5+ levels) may c

### Multiplexer Limitations

**Zellij and herdr support is experimental** and may have limitations compared to tmux. Use tmux for production workflows.
**Zellij, herdr, and rex support is experimental** and may have limitations compared to tmux. Use tmux for production workflows.

#### herdr (experimental)

Expand All @@ -659,3 +660,20 @@ herdr maps one laio config to one workspace inside the dedicated `laio` session.
- `laio session yaml` exports the workspace of the pane laio runs in. It requires `HERDR_WORKSPACE_ID`, which herdr sets in every pane.
- laio marks ownership per workspace with the `LAIO_CONFIG` and `LAIO_VARS` metadata tokens.
- Pane `style` is ignored on herdr.

#### rex (experimental)

rex maps one laio config to one rex session named after the config; laio recognizes its rex sessions by the sidecar store, so labels are plain names. The name must be non-empty; an empty name fails with "Invalid rex session name". A name longer than 128 bytes fails as well.

**Select rex on every command.** Multiplexer selection is per invocation and defaults to tmux. Pass `--muxer rex` on each laio command, or set `LAIO_MUXER=rex`. Without it, laio targets tmux.

- `laio start <config>` builds the whole session in one `session.create` call, then attaches. Starting a config that is already running attaches to it. `--skip-attach` skips the attach.
- Attach runs the bare command `rex do session.select session_id=<full session:-prefixed 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.
- A session without windows fails with `Session '<name>' has no windows`. Each window is capped at 24 blocks and a split depth of 16; a larger layout fails before rex is called.
- `pane_cmd_delay` is applied once before the first pane command is sent.
- Session `env` is ignored: rex has no environment store. `laio` keeps the config path and the template variables in a sidecar record per session.
- The sidecar store is `LAIO_STATE_DIR` when set (used as-is), otherwise `$XDG_STATE_HOME/laio/rex`, otherwise `~/.local/state/laio/rex`.
- `laio stop <config>` runs the shutdown hooks and kills the rex session. `laio stop --all` and `--others` sweep the laio-managed sessions and prune stale records.
- `laio list` shows the laio-managed sessions. It marks ● only for the session laio runs in (`REX_SESSION`). rex exposes no who-displays-what signal, so from outside a rex session every row shows ○.
- `laio session yaml` requires a rex session: it reads `REX_SESSION`. The export reads the tiled layer, so it loses pane commands and ignores floating layers.
- Pane `style` is ignored on rex.
6 changes: 5 additions & 1 deletion docs/content/docs/workflow/managing-configs.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,11 @@ Useful for scripting and automation.
laio session list
```

On tmux and zellij this lists every session of the multiplexer, including sessions laio does not manage. On herdr it lists only laio-managed workspaces.
On tmux and zellij this lists every session of the multiplexer, including sessions laio does not manage. On herdr it lists only laio-managed workspaces. On rex it lists only laio-managed sessions and marks ● only the session laio runs in (`REX_SESSION`); rex exposes no who-displays-what signal, so every other laio-managed session shows ○.

#### rex (experimental)

rex runs one rex session per config, named after the config; laio recognizes its rex sessions by the sidecar store, so labels are plain names. Attach needs Remote Control 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 `env` and pane `style` are ignored. `laio session yaml` loses pane commands and ignores floating layers. Session records live in `LAIO_STATE_DIR` when set, otherwise `$XDG_STATE_HOME/laio/rex`, otherwise `~/.local/state/laio/rex`.

## Deleting Configurations

Expand Down
Loading