loomux (lx)

Git-aware tmux session manager with worktree support, AI agent integration, and powerline theming.

The session management layer for AI-agent-driven development workflows. Manages tmux sessions scoped to git branches and worktrees — start isolated workspaces with one command, apply layouts, track AI agent status in the status bar, and clean up worktrees on session stop.

• Git-aware sessions — one session per branch, auto-named project/branch
• Worktree integration — lx start -b <branch> creates a worktree + tmux session
• AI agent hooks — Claude Code status displayed in tmux status bar (idle/working/error)
• Layouts — predefined pane arrangements (claude, dev, focus, or custom via .lxrc.yml)
• Powerline theming — built-in themes + tmux-powerkit integration, session-scoped
• Plugin management — TPM-compatible plugin install/update
• Pure bash — no compiled dependencies, just tmux + git

Install

git clone https://github.com/sibhod/loomux.git ~/loomux
cd ~/loomux
bash install.sh

Requires tmux and git. Recommends yq (YAML config) and fzf (fuzzy selection). The installer checks for all four and shows platform-specific install commands for anything missing.

Quick Start

cd ~/projects/my-app
lx init                  # create .lxrc.yml config
lx start                 # start a session
lx start -l claude       # start with a specific layout
lx start -b feat/auth    # start in a git worktree

Commands

| Command | Alias | Description | |---------|-------|-------------| | lx | | Interactive menu (list sessions or start new) | | lx init | lx i | Initialize .lxrc.yml for current repo | | lx start | lx s | Start or reattach to a session | | lx stop | lx x | Stop session with cleanup hooks | | lx list | lx ls | List sessions grouped by repo | | lx switch | lx sw | Interactive session picker (fzf) | | lx layout | lx l | Swap layout or list available layouts | | lx theme | lx t | Change or list themes | | lx menu | lx m | Popup menus (sessions, layouts, themes) | | lx split | | SSH-aware pane splits | | lx palette | lx p | Command palette (Ctrl+Space) | | lx keys | lx k | Show keybinding reference | | lx attach | lx a | Attach to session by ID or name | | lx X | | Stop all sessions (with confirmation) |

lx init

-n, --name NAME   Set project name (default: prompt or repo dirname)
-h, --help        Show this help

lx start

-b, --branch BRANCH   Create/use worktree for branch
-l, --layout LAYOUT   Apply layout (default, claude, dev, focus)
-d, --dir DIR         Override working directory
--no-worktree         Use branch without worktree

lx stop

-s, --session NAME    Stop a specific session
-a, --all             Stop all lx sessions
-f, --force           Skip confirmation prompts

lx list

-a, --all             Show all sessions, not just current repo
-s, --simple          Simple output (for scripting)

Layouts

Four built-in layouts. Define custom layouts in .lxrc.yml.

| Layout | Description | |--------|-------------| | default | Main terminal (60%) + side stack: shell top, htop bottom | | claude | Main terminal (55%) + Claude Code (65% of right) + htop | | dev | Editor (65%) + dev server + log tail | | focus | Single full-screen pane |

Themes

Four built-in themes. Set via lx theme <name> or theme: in .lxrc.yml.

| Theme | Description | |-------|-------------| | default | Dark, understated (bottom bar) | | powerkit | Powerline-style (top bar) | | dracula | Dracula color palette | | minimal | Clean, distraction-free |

Per-Project Config

Create .lxrc.yml in your repo root, or run lx init:

project: my-app
default_layout: claude
theme: default

# Session naming pattern (default: "{project}/{branch}")
# Variables: {project}, {branch}, {worktree}
# session_name: "{project}-{branch}"

layouts:
  claude:
    - pane: main
      position: left
      size: "55%"
      command: ""
    - pane: claude
      position: right-top
      size: "65%"
      command: "claude"
    - pane: monitor
      position: right-bottom
      size: "35%"
      command: "htop"

worktree:
  auto_create: true
  cleanup_on_stop: ask       # ask | always | never
  base_dir: ../.worktrees

env:
  NODE_ENV: development

hooks:
  on_start:
    - "echo 'Starting {{project}}'"
  on_stop:
    - "kill-port 3000"

# Hide status bar elements (theme controls appearance)
status_bar:
  show_branch: true
  show_worktree: true
  show_session_count: true

See .lxrc.example.yml for the full reference.

Session Naming

Sessions are named repo/branch by default (e.g., my-app/main, my-app/feat-auth), so lx list groups sessions by project and the status bar always shows where you are.

Configure the pattern in .lxrc.yml:

session_name: "{project}/{branch}"     # my-app/feat-auth (default)

session_name: "{project}-{branch}"     # my-app-feat-auth

session_name: "{project}/{worktree}"   # uses worktree dirname

Keybindings

Inside an lx session, these bindings are available. Run lx keys (or prefix + ?) for the full list.

Sessions & Menus (prefix = Ctrl-b)

| Binding | Action | |---------|--------| | Ctrl + Space | Command palette (no prefix) | | prefix + T | Main lx menu | | prefix + s | Session switcher (fzf popup) | | prefix + S | Quick session menu | | prefix + n | New session from branch | | prefix + X | Stop current session | | prefix + x | Close pane (quick, no confirm) | | prefix + w | Close window (quick, no confirm) | | prefix + L | List all sessions | | prefix + ? | Show keybinding reference |

Navigation (no prefix needed)

| Binding | Action | |---------|--------| | Shift + ←↑↓→ | Focus pane in direction | | Alt + h/j/k/l | Focus pane (vim-style) | | Alt + [ / ] | Previous/next window | | Alt + c | New window (SSH-aware) | | Alt + w | Close window (with confirm) |

Pane Swap

| Binding | Action | |---------|--------| | Alt+Shift + H/J/K/L | Swap pane (vim-style) | | Ctrl+Shift + ←↑↓→ | Swap pane (no prefix) |

Pane Resize

| Binding | Action | |---------|--------| | Alt+Shift + ←↑↓→ | Resize pane (no prefix, repeatable) | | prefix + H/J/K/L | Resize pane (repeatable) |

Layouts

| Binding | Action | |---------|--------| | prefix + W | Layout swap menu | | Alt + 1/2/3/4 | Quick layout (default/claude/dev/focus) |

Splits (prefix required)

| Binding | Action | |---------|--------| | prefix + \| | Vertical split (SSH-aware) | | prefix + - | Horizontal split (SSH-aware) | | prefix + \ | Vertical split (simple) | | prefix + _ | Horizontal split (simple) | | prefix + m | Toggle zoom (maximize/restore) |

Other

| Binding | Action | |---------|--------| | prefix + G | Worktree menu | | prefix + r | Reload config |

Worktree Workflow

lx start -b feat/new-api

This creates a git worktree at ../.worktrees/my-app-feat-new-api, starts a tmux session scoped to it, and opens all panes in the worktree directory.

When you lx stop, clean worktrees are removed automatically. Dirty worktrees (uncommitted changes) trigger a warning first. Control this with worktree.cleanup_on_stop in .lxrc.yml.

SSH Auto-Reattach

Add this to .bashrc on the remote machine to reattach to detached sessions on SSH reconnect:

if [[ -n "$SSH_CONNECTION" && -z "$TMUX" ]]; then
  detached=$(tmux list-sessions -F '#{session_name} #{session_attached}' 2>/dev/null \
    | awk '$2 == "0" {print $1}' | head -1)
  if [[ -n "$detached" ]]; then
    echo "lx: Reattaching to '$detached'..."
    sleep 0.5
    tmux attach-session -t "=$detached"
  fi
fi

Project Structure

lx/
├── lx                  # CLI entry point + command dispatch
├── install.sh          # Installer (symlink + dep check)
├── src/
│   ├── lx-utils.sh     # Shared utilities, config, git helpers
│   ├── lx-init.sh      # Project initialization
│   ├── lx-start.sh     # Session creation
│   ├── lx-stop.sh      # Session cleanup
│   ├── lx-list.sh      # Session listing
│   ├── lx-switch.sh    # Session switching
│   ├── lx-layout.sh    # Layout management
│   ├── lx-menu.sh      # Popup menus
│   ├── lx-split.sh     # SSH-aware pane splits
│   └── lx-worktree.sh  # Git worktree handling
├── conf/
│   ├── keybindings.conf
│   └── status-bar.conf
├── themes/             # default, powerkit, dracula, minimal
├── test/               # Test suite (bash test/run-tests.sh)
└── .lxrc.example.yml   # Config reference

License

MIT