tmuxp - ein Session-Manager für tmux, der Sessions über deklarative YAML- oder JSON-Dateien lädt, einfriert und konvertiert.

Das Projekt basiert auf libtmux und wird aktiv auf GitHub entwickelt. Die Idee ist simpel. Statt jeden Morgen fünf Fenster manuell zu öffnen und Befehle einzutippen, definierst du deine Arbeitsumgebung einmal als Datei und lädst sie mit einem Befehl.

Was tmuxp macht

tmuxp verwaltet tmux-Sessions auf Basis von Konfigurationsdateien. Du beschreibst darin, welche Fenster und Panes geöffnet werden sollen und welche Befehle darin ausgeführt werden. Beim Laden baut tmuxp die Session genau so auf, wie du sie definiert hast.

Das funktioniert mit YAML und JSON. tmuxp unterstützt auch die Formate von tmuxinator und teamocil, was den Umstieg erleichtert, wenn du bereits eine dieser Lösungen nutzt.

Installation

tmuxp lässt sich auf verschiedene Weisen installieren. Je nach System und Vorliebe gibt es mehrere Wege.

Unter Debian und Ubuntu läuft es über apt.

sudo apt install tmuxp

Für Manjaro

sudo pamac install tmuxp

Andere Installationsarten sind auf github beschrieben.

Eine Session laden

Das Herzstück von tmuxp ist der load-Befehl. Du definierst eine Session in einer YAML-Datei und lädst sie damit.

Ein einfaches Beispiel sieht so aus.

# yaml Datei
session_name: my-project
windows:
  - window_name: editor
    panes:
      - shell_command:
          - vim
      - shell_command:
          - git status

Diese Datei speicherst du als my-project.yaml und lädst sie dann.

tmuxp load my-project.yaml

Erklärung:

  1. tmuxp baut daraufhin eine Session mit dem Namen my-project auf.
  2. Darin befindet sich ein Fenster namens editor, das in zwei Panes aufgeteilt ist.
  3. Im ersten Pane läuft vim
  4. im zweiten wird git status ausgeführt.

Komplexere Konfiguration

tmuxp kann deutlich mehr als nur einfache Fenster. Du kannst Layouts definieren, Befehle vor dem Start aller Panes ausführen und mehrere Panes mit unterschiedlichen Aufgaben bestücken.

Ein Beispiel mit vier Panes und einem vordefinierten Layout.

session_name: 4-pane-split
windows:
  - window_name: dev window
    layout: tiled
    shell_command_before:
      - cd ~/
    panes:
      - shell_command:
          - cd /var/log
          - ls -al | grep \.log
      - echo second pane
      - echo third pane
      - echo fourth pane

Erklärung:

  1. Der Parameter shell_command_before führt einen Befehl in allen Panes aus, bevor die eigentlichen Befehle starten. In diesem Fall wechselt jeder Pane zuerst ins Home-Verzeichnis.
  2. Der Parameter layout legt fest, wie die Panes angeordnet werden.
  3. tiled bedeutet, dass alle Panes gleichmäßig verteilt werden.

Größenangaben

Die layout-Option

Die zentrale Option dafür ist layout. Du kannst entweder einen vordefinierten Namen verwenden oder einen spezifischen Layout-String, den tmux selbst generiert.

Vordefinierte Layouts sind einfach zu nutzen, geben dir aber weniger Kontrolle:

windows:
  - window_name: dev
    layout: main-horizontal
    panes:
      - vim
      - git status

Weitere gängige Namen sind tiled, even-horizontal und even-vertical.

Spezifische Größen und Positionen

Wenn du genau definieren möchtest, wie die Panes angeordnet sind, musst du den Layout-String von tmux verwenden. Dieser String ist eine kodierte Beschreibung der Aufteilung und Größe jeder Zelle.

  1. Baue eine tmux-Session mit den gewünschten Pane-Aufteilungen manuell auf.
  2. Frage das aktuelle Layout ab:
tmux list-windows
  1. Kopiere den Layout-String (der lange Code nach layout:) in deine tmuxp-YAML-Datei.

Ein Beispiel für einen solchen String sieht so aus:

layout: 382a,80x60,0,0[80x10,0,0,0,80x10,0,11,1,80x10,0,22,2,80x8,0,33,3]

Die Zahlen kodieren Breite x Höhe und Position jedes Panes. Das ist präzise, aber nicht besonders lesbar.

Alternative % für einfache Anpassungen

Wenn du nur die Höhe des Haupt-Panes bei Layouts wie main-horizontal oder main-vertical anpassen möchtest, kannst du die Option main-pane-height verwenden. Diese kann in Zeilen oder seit tmuxp 1.46.0 auch in Prozent angegeben werden.

windows:
  - window_name: rust-study
    layout: main-horizontal
    options:
      main-pane-height: 67%
    panes:
      - vim
      - cargo run

Das ist oft der praktischere Weg, wenn du nur das Größenverhältnis zwischen Haupt- und Nebenpanes steuern willst.

Projekte und Konfigurationsverzeichnisse

tmuxp sucht nach Konfigurationen in verschiedenen Verzeichnissen. Wenn du eine Datei mit dem Namen .tmuxp.yaml oder .tmuxp.json in einem Projektordner ablegst, kannst du sie direkt über den Ordnerpfad laden.

tmuxp load path/to/my/project/

Für benutzerweite Konfigurationen durchsucht tmuxp mehrere Verzeichnisse automatisch. Das ist praktisch, wenn du deine Sessions von überall aus laden möchtest, ohne den vollständigen Pfad anzugeben.

  • $TMUXP_CONFIGDIR, falls gesetzt
  • $XDG_CONFIG_HOME, üblicherweise $HOME/.config/tmuxp/
  • $HOME/.tmuxp/

Wenn deine Konfiguration unter ~/.config/tmuxp/mysession.yaml liegt, reicht folgender Befehl.

tmuxp load mysession

Du kannst auch mehrere Sessions gleichzeitig laden.

tmuxp load mysession ./another/project/

Oder der Session einen eigenen Namen geben.

tmuxp load -s session_name ./mysession.yaml

Sessions einfrieren (speichern)

Manchmal hast du eine tmux-Session bereits aufgebaut und möchtest sie als Konfiguration speichern. Dafür gibt es den freeze-Befehl.

tmuxp freeze session-name

tmuxp erstellt dann eine YAML- oder JSON-Datei, die den aktuellen Zustand der Session beschreibt. Layout, Pane-Pfade, Fensternamen und Sessionnamen werden übernommen. Das ist praktisch, wenn du eine Session spontan aufgebaut hast und sie später reproduzieren möchtest.

Der tmuxp freeze-Befehl speichert die Datei standardmäßig nicht in einem festen Verzeichnis. Stattdessen wirst du beim Ausführen gefragt, wo die Datei gespeichert werden soll.

Wo speichern

Wenn du tmuxp freeze session-name ausführst, bietet dir tmuxp an, den Zustand als .yaml- oder .json-Datei zu speichern .

Beim Ausführen von tmuxp freeze wirst du interaktiv gefragt, wo die Datei gespeichert werden soll. Du kannst den Speicherort dann angeben oder einen vorgeschlagenen Pfad bestätigen

Speicherorte für Konfigurationen

Wenn du deine gefrorene Session später bequem über den Namen laden möchtest, solltest du sie in einem der folgenden Verzeichnisse ablegen :

  • ~/.tmuxp/ – das klassische Verzeichnis
  • ~/.config/tmuxp/ – der XDG-Standardpfad
  • Projektlokal – als .tmuxp.yaml oder .tmuxp.json im Projektordner

Eigenen Pfad angeben

Du kannst den Speicherort auch direkt mit dem -o oder --save-to Parameter festlegen .

tmuxp freeze my-session -o /pfad/zur/datei.yaml

Konvertieren zwischen Formaten

Wenn du eine Konfiguration von YAML nach JSON oder umgekehrt umwandeln möchtest, geht das mit dem convert-Befehl.

tmuxp convert filename

tmuxp zeigt dir die neue Datei an und fragt nach Bestätigung. Wenn du den Prompt automatisch bestätigen möchtest, kannst du den Parameter -y verwenden.

tmuxp convert -y filename

Die tmuxp-Shell

Seit Version 1.6.0 gibt es den Befehl tmuxp shell. Damit startest du eine Python-Konsole, die mit dem aktuellen Server, der Session und dem Fenster als libtmux-Objekte vorgeladen ist.

tmuxp shell

Das ist nützlich, wenn du tmux-Sessions skripten oder automatisieren möchtest.

Plugins und Erweiterungen

tmuxp hat ein Plugin-System, mit dem du eigenes Verhalten hinzufügen kannst. Das ist interessant, wenn du spezielle Anforderungen hast, die über die Standardfunktionen hinausgehen.

Ein Pre-Load-Hook erlaubt es dir, benutzerdefinierte Skripte auszuführen, bevor tmux geladen wird. Das kann zum Beispiel genutzt werden, um Projektabhängigkeiten zu installieren.

Debugging

Wenn beim Laden einer Session etwas schiefgeht, kannst du die Ausgabe in eine Logdatei schreiben.

tmuxp load --log-file <log-file-name> .

Für Bugreports gibt es den Befehl tmuxp debug-info, der Systeminformationen sammelt.

tmuxp debug-info

Load im Hintergrund

Wenn du eine Session laden möchtest, ohne dich direkt daran anzuhängen, kannst du den Parameter -d verwenden.

tmuxp load -d mysession.yaml

Das ist praktisch, wenn du mehrere Sessions vorbereiten möchtest und später entscheiden willst, welche du verwendest.

Fazit

tmuxp ist ein Werkzeug, das tmux für mich deutlich angenehmer macht. Statt jedes Mal die gleiche Session von Hand aufzubauen, definiere ich sie einmal und lade sie mit einem Befehl. Oder kopiere sie auf mehrere Rechner, so dass ich sie nur ein einziges Mal definieren muss. Das spart Zeit und reduziert Fehler.

Besonders praktisch finde ich die Möglichkeit, Sessions einzufrieren. Wenn ich spontan eine Session aufgebaut habe, die ich öfter brauche, speichere ich sie einfach als Konfiguration und habe sie beim nächsten Mal sofort parat.

Danke an Markus aus dem Fedivers https://social.row-social.de/@markus , der mich darauf aufmerksam gemacht hat!

Quellen und Download

tmuxp ist als Open-Source-Software unter der MIT-Lizenz verfügbar.