Learn Tmux - Scripting, Automation & Command Line

#Introduction

In episode 13 we covered persistence and data management — saving and restoring sessions with tmux-resurrect and tmux-continuum, rescuing scrollback with capture-pane, and real-time logging with pipe-pane. The restore ability is most valuable when triggered from inside a script, and that brings us to one question: what if we don't need restore at all, because sessions are simply recreated deterministically from scratch every time?

In this episode we cover scripting, automation, and the command line: building sessions without human interaction, arranging declarative layouts with tmuxp and tmuxinator, and using the tmux CLI as a stable scripting foundation. The end goal is a workspace that can be bootstrap-ed with one command — on a laptop, in CI, or on a production server — with identical results everywhere.

#Why Session Automation is a Production Skill

There's a big difference between "opening tmux and arranging panes manually" and "running one script that prepares everything". The first is a personal habit; the second is a reproducible, shareable artifact. When a new team member joins, they don't need to read a 20-step setup document — just run bootstrap.sh and the workspace appears in the same form the whole team uses.

Automation also changes how teams handle environments. Dev server, test runner, and log tailing rearranged manually every morning is a huge cumulative waste of time. The same script also becomes test material: because it's deterministic, it can be run on a CI machine to ensure the workspace structure isn't broken before a human touches it.

#Non-interactive Commands: Building a Session Without Hands

Everything you can do via keybindings inside tmux can be done from a plain shell as a non-interactive command. This is the bridge between tmux and the shell we caught a glimpse of in episode 12 — and here we use it as the main language.

#tmux new -d: Detached Sessions

The key to all automation is the -d flag on new-session. The session is created detached — the tmux server stands, the session exists, but no client is attached. This matters because a script must not hijack the active terminal:

tmux new -d -s dev -n editor
tmux new -d -s api -n main -c /srv/api
tmux ls

The first line creates a dev session with its first window named editor. The second creates an api session that lands directly in the /srv/api working directory. The third line verifies both sessions are registered — without a single client attached.

#send-keys: Typing from a Distance

Once the session stands, send-keys sends keystrokes to a specific pane as if you typed them. This is how a script runs commands inside a pane without human intervention:

tmux send-keys -t dev "cd ~/code/web && nvim ." Enter
tmux send-keys -l "ls -la"
tmux send-keys -t api:0 "make migrate" Enter

Note two things. First, Enter is sent as the last argument — without it, the command is only written at the prompt and never executed. Second, the -l flag sends text literally without interpretation; use -l when the text contains special characters you don't want tmux to process.

#select-pane and select-window: Setting Focus

Focus position within a session is controlled with select-pane and select-window. A script arranges the workspace then determines which pane becomes active when you attach:

tmux select-window -t dev:0
tmux select-pane -t dev:0.1
tmux attach-session -t dev

The first line selects window 0, the second moves focus to pane number 1 in that window, and the third attaches the client. The result: when the terminal opens, you land directly in the most-used pane — not a random first pane.

#Target Syntax: Session:Window.Pane

Almost all of the commands above use a target in the session:window.pane form. This is the full address of a pane, and understanding it is a requirement for writing on-target scripts:

The rule of thumb: a missing part means "the currently active one". dev:0.1 is the most explicit and safest form for scripts, because it doesn't depend on the focus state at the time. Pane numbering follows the pane-base-index we set in episode 12.

#Workspace Bootstrap Script

Now let's combine everything into one complete script that prepares a development workspace. This script uses the has-session || new-session idiom we already know: if the session already exists, don't create a duplicate — just attach.

#!/usr/bin/env bash
project="${1:-$PWD}"
name="$(basename "$project")"
if ! tmux has-session -t "$name" 2>/dev/null; then
  tmux new-session -d -s "$name" -c "$project" -n editor
  tmux send-keys -t "$name:0" "cd '$project' && nvim ." Enter
  tmux new-window -t "$name" -n server -c "$project"
  tmux send-keys -t "$name:1" "npm run dev" Enter
  tmux new-window -t "$name" -n logs -c "$project"
  tmux send-keys -t "$name:2" "tail -f log/app.log" Enter
  tmux select-window -t "$name:0"
fi
tmux attach-session -t "$name"

Let's dissect the flow line by line:

• The session name is taken from the project folder name via basename — in /home/devnull/work/api-gateway, the session is automatically named api-gateway.
• The if ! tmux has-session guard prevents recreating an already-alive session; it also acts as a natural return code, as we'll discuss in the CLI reference section.
• new-session -d creates the first editor window, then send-keys opens Neovim inside it.
• new-window adds the server and logs windows, each with its own initial command via -c and send-keys.
• select-window moves focus back to the editor, and attach-session attaches the client.

Save it as bootstrap-dev.sh, give it permission with chmod +x, and you have a single entrance to the whole workspace.

#tmuxp and tmuxinator: Declarative Layouts

Shell scripts give full control, but for more complex layouts, writing a series of new-window and send-keys becomes verbose. That's where tmuxp and tmuxinator come in: both describe a session as a config file — YAML in tmuxp, and YAML in tmuxinator too — and build the session from that description. The layout becomes a reviewable document, not a sequence of commands to read line by line.

#tmuxp

session_name: web
start_directory: ~/code/web
windows:
  - window_name: editor
    panes:
      - shell_command: nvim .
  - window_name: server
    layout: main-horizontal
    panes:
      - shell_command: npm run dev
      - shell_command: tail -f log/app.log

This file describes a web session with two windows: editor opening Neovim, and server with a main-horizontal layout containing the dev server and log tailing. Running it is a single command:

tmuxp load tmuxp.yaml

#tmuxinator

tmuxinator's approach is almost identical, with a slightly different YAML structure:

name: web
root: ~/code/web
windows:
  - editor: nvim .
  - server:
      layout: main-horizontal
      panes:
        - npm run dev
        - tail -f log/app.log

tmuxinator start web

Which one to choose? Here's the practical comparison:

Both build sessions by calling the same tmux commands we've already learned — so the command-line understanding you build in this episode still applies behind the scenes of both tools.

#CLI Reference for Scripting

#list-commands and show-options as Sources of Truth

There's no need to memorize all tmux commands. tmux list-commands prints the complete list of commands with their syntax — a cheat sheet always up-to-date with the installed version:

tmux list-commands
tmux list-commands new-session
tmux show-options -g base-index

The first line shows all commands, the second shows new-session details, and the third shows that show-options can also serve as a default-value reference. For scripting, the list-sessions, list-windows, and list-panes commands are the data source for the session structure.

#Parsing Output for Automation

List command output can be shaped with the -F flag and a format string — a technique using the format variables we learned in episode 9. This is what makes parsing deterministic:

tmux list-sessions -F '#{session_name}'
tmux list-panes -t dev:0 -F 'pane #{pane_index}: #{pane_current_command}'
tmux list-sessions -F '#{session_name}' | grep -x dev

The -F format replaces the usual visual form with consistent data lines — one field per placeholder — so grep, awk, or cut can process it without tripping over decorative text.

#Exit Codes as Signals

A script determines its next step from the tmux command's exit code. The most useful is has-session: it exits with code 0 if the session exists, and 1 if not. This is the foundation of the idiom we used in the bootstrap script earlier.

if tmux has-session -t dev 2>/dev/null; then
  echo "session dev ada"
else
  echo "session dev belum ada"
fi

By checking exit codes, the script becomes idempotent: running it twice produces no side effects. This is an important principle for all automation that will run repeatedly, including from cron or CI.

#Common Pitfalls

1. Forgetting to add Enter to send-keys. Without Enter, the command just accumulates at the prompt and never executes. Always end the keystroke sequence with Enter unless you deliberately want to leave the prompt waiting.

2. Running new-session without -d inside tmux. Without -d, tmux tries to attach a client to the new session and conflicts with the active session. Create detached, then attach-session or switch-client explicitly.

3. Skipping the has-session guard. A script that creates a session without checking will pile up duplicate sessions every time it runs. Always use the has-session idiom or make it idempotent.

4. Relying on default numbering without pane-base-index. A script assuming panes start at 0 will miss its target on a machine with setw -g pane-base-index 1. Write targets with pane IDs or ensure consistent indexing across machines.

5. Using absolute paths in a shared tmuxp/tmuxinator config. start_directory: /home/username/... breaks on other people's machines. Use ~ or variables like $HOME.

6. Not checking exit codes in multi-command flows. If new-session fails, the following send-keys commands will fail with confusing messages. Check exit codes and stop early with set -e or explicit guards.

#Conclusion

This episode turned you from a tmux user into a workspace builder. You understand non-interactive commands — new -d, send-keys, select-pane, select-window — along with the session:window.pane target syntax, can write idempotent bootstrap scripts, describe declarative layouts with tmuxp and tmuxinator, and read the tmux CLI as a data source and signal via exit codes.

Key points to take away:

• -d + send-keys is the basic combination of all tmux automation.
• An explicit session:window.pane target makes scripts deterministic.
• The has-session idiom makes scripts idempotent and safe to re-run.
• tmuxp/tmuxinator turn layouts into reviewable, shareable declarative documents.

Scripts build the structure; next we make tmux react to what happens inside that structure. In episode 15 we'll cover hooks and event-driven automation — triggering automatic commands on events like pane-exited and client-attached, integrating with development tools, and avoiding infinite loops. See you in episode 15!