tmux-session-json

tmux-session-json or tsj is a Bash script that automates tmux session creation based on an external JSON configuration. You can define session name, windows, pane splits, commands, and focus settings entirely in JSON—no more hard-coded tmux commands in your scripts.

Features:

• External JSON config: define your session structure in config.json
• Window & pane management: automatic creation of windows and panes with custom splits and sizes
• Named & custom layouts: supports tmux’s predefined layouts and raw layout strings
• Command execution: send setup commands to each pane
• Focus control: per-window focus_pane and global focus_win options
• Index support: respects your tmux base-index and pane-base-index
• Secure: uses jq here-strings and mapfile to avoid injection
• Help & usage: --help/-h flags and input validation
• Create default config in project (session) root

Requirements

(Should be present on most distributions by default.)

• Bash
• Tmux
• jq (json command line processor)

Installation

Call sudo make install from project root, where MakeFile resides. Optionally add -nto dry-run.

Usage

# Run from anywhere when installed
tsj [OPTIONS] [CONFIG_FILE]

# Run without Installation
bash /path/to/your/tsj_bash/tsj.sh [OPTIONS] [CONFIG_FILE]

Options:

--init creates default config file in cwd. if [CONFIG_FILE] passed as arg, it's used as template. -h, --help Show help message and exit

Arguments:

CONFIG_FILE Path to JSON configuration file (defaults to XDG config locations)

Examples:

# 0. Initiate (create) config `tsj.json` in cwd
tsj --init

# 1. Create or attach to session defined in tsj.json in cwd
tsj

# 2. Specify a custom config file
tsj ./tmux/project-config.json

# 3. Display help
./tsj.sh --help

JSON Configuration

Example config.json:

{
  "session": {
    "name": "MySession",
    "focus_win": "main_window"
  },
  "windows": [
    {
      "name": "main_window",
      "focus_pane": "main",
      "panes": [
        {
          "id": "main",
          "commands": ["cd ~/project", "vim ."]
        },
        {
          "id": "terminal",
          "split": "horizontal",
          "size": "30%",
          "commands": ["htop"]
        }
      ]
    },
    {
      "name": "monitor",
      "layout": "tiled",
      "focus_pane": "sys",
      "panes": [
        { "id": "sys", "commands": ["htop"] },
        {
          "id": "net",
          "split": "vertical",
          "size": "50%",
          "commands": ["watch ss -tuln"]
        },
        {
          "id": "log",
          "split": "vertical",
          "size": "50%",
          "commands": ["tail -f /var/log/syslog"]
        }
      ]
    }
  ]
}

Json options:

    session.name: tmux session name
    session.focus_win (optional): window to select at the end
    window.name: window name
    window.layout (optional): tmux layout name or raw layout string
    window.focus_pane (optional): pane to select after splitting
    pane.id: identifier for focus lookup
    pane.split: "horizontal"/"vertical" for custom splits
    pane.size: percentage for split (e.g., "30%")
    pane.commands: array of commands to send to that pane