tmuxifier/AGENTS.md

AGENTS.md

This file provides guidance to AI Agents when working with code in this repository.

Project Overview

Tmuxifier is a shell-based tool for creating and managing complex Tmux session and window layouts. Users write layout files as shell scripts that use tmux commands and helper functions to define session/window configurations.

Architecture

Core Components

• bin/tmuxifier: Main executable that bootstraps the environment, validates Tmux version (≥1.6), and dispatches to libexec commands
• libexec/: Command implementations (tmuxifier-*, e.g., tmuxifier-load-session, tmuxifier-new-window)
• lib/layout-helpers.sh: Helper functions available within layout files (new_window, split_v, split_h, run_cmd, select_pane, etc.)
• lib/runtime.sh: Runtime environment loader sourced by layout files
• lib/env.sh: Sets up TMUXIFIER_LAYOUT_PATH (defaults to $TMUXIFIER/layouts)
• templates/: Templates for new session.sh and window.sh layout files
• examples/: Example layout files demonstrating usage

Layout File Types

Session layouts (*.session.sh):

• Define entire Tmux sessions with multiple windows
• Must call initialize_session to create the session
• Can load window layouts via load_window or define windows inline
• Must call finalize_and_go_to_session at the end
• Can set session_root for default directory

Window layouts (*.window.sh):

• Define single window configurations with panes
• Loaded into existing sessions or from session layouts
• Can set window_root for window-specific directory
• Use helper functions to split panes and run commands

Key Concepts

• Layout files are executed as shell scripts with lib/layout-helpers.sh sourced
• Helper functions wrap tmux commands, managing session/window context
• The tmux command itself is aliased to tmuxifier-tmux wrapper
• Session creation moves default window to position 999, then kills it in finalize_and_go_to_session
• TMUXIFIER_TMUX_OPTS allows passing custom arguments to tmux

Development Commands

Testing

Tests use bashunit framework. Use deepwiki MCP tool to lookup bashunit documentation if needed.

make test                                  # Run all tests
make test FILE=tests/lib/util/foo_test.sh  # Run a single test file
make bootstrap                             # Fetch test dependencies

Tests are located in tests/ directory and follow bashunit conventions. Test files are named *_test.sh.

Legacy tests in test-legacy/ use test-runner.sh framework with assert.sh and stub.sh libraries. Run with make test-legacy.

Manual Testing

# Create and load a test window layout
./bin/tmuxifier new-window test-window
./bin/tmuxifier load-window test-window

# Create and load a test session layout
./bin/tmuxifier new-session test-session
./bin/tmuxifier load-session test-session

# List available layouts
./bin/tmuxifier list-sessions
./bin/tmuxifier list-windows

Code Style

• Shell scripts follow Bash conventions
• 2-space indentation
• Functions document arguments in comments
• Use local variables for function scope
• Prefer [ ] over [[ ]] for basic tests
• Command substitution uses $() not backticks

Important Implementation Details

Helper Function Pattern

Helper functions in lib/layout-helpers.sh follow this pattern:

function_name() {
  # Parse optional arguments
  if [ -n "$1" ]; then local arg=(-flag "$1"); fi

  # Execute tmux command with session/window context
  tmuxifier-tmux command -t "$session:$window" "${arg[@]}"

  # Update state if needed
  __go_to_window_or_session_path
}

Tmux Version Handling

Code must support Tmux 1.6+. Version-specific behavior uses tmuxifier-tmux-version comparisons:

if [ "$(tmuxifier-tmux-version "1.9")" == "<" ]; then
  # Tmux 1.8 and earlier
else
  # Tmux 1.9 and later
fi

Path Expansion

Use __expand_path to handle ~ and variables in paths:

session_root() {
  local dir="$(__expand_path $@)"
  if [ -d "$dir" ]; then
    session_root="$dir"
  fi
}

Environment Variables

• TMUXIFIER: Set to installation directory (auto-detected from bin location)
• TMUXIFIER_LAYOUT_PATH: Custom layouts directory (default: $TMUXIFIER/layouts)
• TMUXIFIER_TMUX_OPTS: Custom arguments passed to tmux
• TMUXIFIER_TMUX_ITERM_ATTACH: Set to "-CC" for iTerm2 integration
• TMUXIFIER_NO_COMPLETE: Disable shell completion if set
• TMUXIFIER_MIN_TMUX_VERSION: Minimum required Tmux version (1.6)