A tmux session manager that creates sessions from YAML configuration files.

• Create tmux sessions with predefined window layouts
• Complex pane splits (horizontal/vertical, nested)
• Run commands in panes on session creation
• Fuzzy finder for session selection
• Config file includes (compose configs from multiple files)
• Quick project session creation from configurable projects directory

Precompiled binaries for tx are available for Linux, macOS and Windows:

• Visit the Releases Page to download the latest version for your platform.

Install from a custom tap:

brew install chenasraf/tap/tx

go install github.com/chenasraf/tx@latest

git clone https://github.com/chenasraf/tx.git
cd tx
make build # build only
make install # build & install to ~/.local/bin

# Open a session (fuzzy finder if no name given)
tx [session-name]

# List all configurations and active sessions
tx list
tx ls -b              # bare output (just names)
tx ls -s              # show only active sessions

# Show configuration details
tx show <name>
tx show <name> -j     # JSON output

# Edit configuration file
tx edit
tx edit -c ~/local.yaml   # edit a specific config file

# Create a temporary session
tx create
tx create -r ~/myproject -w src -w lib
tx create -s          # save to config
tx create -S          # save only (don't create)

# Quick project session from projects directory
tx prj [name]
tx prj -s             # save to config

# Attach to existing session
tx attach [name]

# Remove a configuration
tx rm <name>
tx rm <name> -c ~/local.yaml  # remove from a specific config file

# Kill a running session
tx kill               # kill current session
tx kill <name>        # kill specific session

tx searches for configuration files in these locations (in order):

1. Home directory (~)
2. $XDG_CONFIG_HOME (if set)
3. ~/.config
4. %APPDATA% (Windows, if set)

File patterns searched:

• tmux.yaml / tmux.yml
• .tmux.yaml / .tmux.yml

You can compose your configuration from multiple files using the include setting under .config. Included files are merged with the main config, with later includes taking precedence. See Config Includes for details.

# Simple session
myproject:
  root: ~/Dev/myproject
  windows:
    - ./src
    - ./lib
    - ./test

# Session with named windows
webapp:
  root: ~/Dev/webapp
  windows:
    - name: editor
      cwd: ./src
    - name: server
      cwd: ./backend
      layout:
        cwd: .
        cmd: npm run dev
        split:
          direction: v
          child:
            cwd: .
            cmd: npm run watch

# Session with initial window override
webapp:
  root: ~/Dev/webapp
  initial_window: 0 # open on the "general" window instead of the first configured one
  windows:
    - ./src
    - ./lib

# Session with complex layout
fullstack:
  root: ~/Dev/fullstack
  blank_window: true # add a blank window at the start
  windows:
    - name: dev
      cwd: ./frontend
      layout:
        cwd: .
        cmd: npm start
        split:
          direction: h
          child:
            cwd: ../backend
            cmd: go run .
            split:
              direction: v
              child:
                cwd: .
                cmd: tail -f logs/app.log

Windows can be specified as:

String - just a directory path:

windows:
  - ./src
  - ./lib

Object - with name, cwd, and optional layout:

windows:
  - name: mywindow
    cwd: ./src
    layout: ...

Layouts define pane splits and commands:

String - just a directory:

layout: ./src

Array - horizontal splits:

layout:
  - ./src
  - ./lib
  - ./test

Object - full pane configuration:

layout:
  cwd: .
  cmd: npm start # command to run
  zoom: true # zoom this pane
  clock: false # show tmux clock mode
  split:
    direction: h # h (horizontal) or v (vertical)
    child:
      cwd: ./other
      cmd: npm test
      split: # nested splits
        direction: v
        child:
          cwd: .
          clock: true # show clock in this pane

The special .config key is reserved for global settings and won't be treated as a session:

.config:
  shell: /bin/zsh
  projects_path: ~/Dev

myproject:
  root: ~/Dev/myproject
  # ...

The default_layout setting configures the default pane arrangement for windows. Each pane can have:

Example - single pane with clock:

.config:
  default_layout:
    cwd: .
    clock: true

Example - horizontal split with vertical sub-split (default):

.config:
  default_layout:
    cwd: .
    split:
      direction: h
      child:
        cwd: .
        split:
          direction: v
          child:
            cwd: .
            clock: true

Define reusable layouts that can be referenced by name in session configurations:

.config:
  named_layouts:
    dev:
      cwd: .
      cmd: npm run dev
      split:
        direction: h
        child:
          cwd: .
          cmd: npm run test:watch
    simple:
      cwd: .
      clock: true

myproject:
  root: ~/Dev/myproject
  windows:
    - name: main
      cwd: .
      layout: dev # references the "dev" named layout
    - name: logs
      cwd: ./logs
      layout: simple # references the "simple" named layout

The initial_window setting controls which window is selected when a new session is created. Window 0 is the "general" window (created automatically with the session), and configured windows start at index 1. The default is 1 (the first configured window).

This can be set globally under .config and overridden per session:

.config:
  initial_window: 1 # global default

myproject:
  root: ~/Dev/myproject
  initial_window: 0 # override: start on the "general" window
  windows:
    - ./src
    - ./lib

The include setting lets you compose your configuration from multiple files. This is useful for separating machine-specific configs from shared ones, or simply organizing a large config into smaller pieces.

# ~/.tmux.yaml
.config:
  include:
    - ./local.yaml # relative to this file's directory
    - ~/shared/team.yaml # ~ is expanded to home directory
    - /etc/tx/company.yaml # absolute paths work too

myproject:
  root: ~/Dev/myproject

Path resolution:

• Relative paths are resolved relative to the directory of the config file containing the include
• ~ is expanded to the home directory
• Absolute paths are used as-is

Included files can themselves contain include lists (nested includes). Circular includes are detected and skipped. Later includes take precedence over earlier ones when merging.

The shell used for executing commands is determined in this order:

1. Config file - .config.shell in your config file (highest priority)
2. Environment - $SHELL environment variable
3. Auto-detect - First available of /bin/zsh, /bin/bash, /bin/sh

# ~/.tmux.yaml
dotfiles:
  root: ~/.dotfiles
  windows:
    - .
    - ./utils

webapp:
  root: ~/Dev/webapp
  windows:
    - name: code
      cwd: ./src
    - name: server
      cwd: .
      layout:
        cwd: .
        cmd: npm run dev
        split:
          direction: h
          child:
            cwd: .
            cmd: npm run test:watch

# Create a session for current directory
tx create

# Create with specific windows
tx create -r ~/myproject -w src -w lib -w test

# Create and save to config
tx create -r ~/myproject -s

First, configure your projects directory in .config:

.config:
  projects_path: ~/Dev

Then use tx prj to quickly open projects:

# Select from projects directory with fuzzy finder
tx prj

# Open specific project
tx prj myproject

# Open and save to config for future use
tx prj myproject -s

Run tx migrate to automatically migrate your configuration. It finds your existing tmux_local config file and adds it as an include in your main config. Use tx migrate -d for a dry run to preview changes before applying.

In v1.x, tx automatically searched for a tmux_local.yaml (or .tmux_local.yaml) file and merged it with the global config. In v2.x, this implicit behavior is replaced with an explicit include mechanism in .config.

Before (v1.x):

~/.tmux.yaml          # global config (auto-discovered)
~/.tmux_local.yaml    # local config (auto-discovered and merged)

After (v2.x):

# ~/.tmux.yaml
.config:
  include:
    - ./tmux_local.yaml # explicitly include the local config

Your tmux_local.yaml file contents do not need to change — just add the include entry to your main config.

Commands that accepted --local / -l (such as edit, create, remove, prj) now use --config / -c instead, which takes a file path argument.

Before (v1.x):

tx edit -l
tx rm myproject -l
tx create -s -l
tx prj myproject -s -l

After (v2.x):

tx edit -c ~/tmux_local.yaml
tx rm myproject -c ~/tmux_local.yaml
tx create -s -c ~/tmux_local.yaml
tx prj myproject -s -c ~/tmux_local.yaml

I am developing this package on my free time, so any support, whether code, issues, or just stars is very helpful to sustaining its life. If you are feeling incredibly generous and would like to donate just a small amount to help sustain this project, I would be very very thankful!

I welcome any issues or pull requests on GitHub. If you find a bug, or would like a new feature, don't hesitate to open an appropriate issue and I will do my best to reply promptly.

MIT