gremux 0.1.3

A declarative tmux session manager

gremux

A declarative tmux session manager.

[!NOTE] This project is in development. Basic features are implemented, but there is still a long roadmap to cover. If you have any feature requests, leave an issue.

gremux automates the process of launching a tmux session exactly how you want it in a declarative way. That is, given a static configuration file grem.yaml, gremux will parse it and attach you to a session that matches that setup.

This project started when I got tired of having to manually set up my tmux panes and windows each time I rebooted my laptop. Thus, I can spend many hours automating a process that takes literal seconds.

Here is a list of a few similar projects:

• tmuxp: Session manager for tmux, build on libtmux.
• tmuxinator: Manage complex tmux sessions easily
• disconnected: Simple tmux session creator

Why choose gremux?

You don't have to if you don't want. That's the beauty of FOSS. This project was started as something to kill the time while waiting for my experiments during my PhD. I use it as my main tool, and it would be amazing if other people found it useful.

Additionally, I do projects in order to teach myself some design patterns to eventually be a better programmer. I don't mind reinventing the wheel from time to time in order to learn something new.

[!NOTE] The name gremux. I am obsessed with VTubers, and put references everywhere I can. This is a reference to Gigi Murin, whose fanbase are called grems.

Features

• Declarative YAML tmux session configuration on a per-project basis
• Interactive project sessionizer inspired by ThePrimeagen's script
• Saved config templates under ~/.config/gremux/templates/
• Interactive picker for attaching to existing tmux sessions

Installation

1. Install tmux and fzf from your package manager
2. Install with pip
3. Optional: install the questionary package.

pip install gremux

or for arch-based distributions, use some AUR helper like paru

paru -S gremux

Run gremux to open the sessionizer or be prompted to create places.yaml

If you want to use the interactive attach picker or config use --interactive, make sure questionary is installed as well.

Setup

Common places

You must create the (global config) file ~/.config/gremux/places.yaml. To create it, run

gremux places create --source default

This will create a basic places.yaml with your home directory. To add more places, you can manually edit the file or run

gremux places create --add dir1 dir2 dir3

[!TIP] If you use zoxide, then you can choose to use the database as a source

gremux places create --source zoxide

And optionally you can add the --maximum N flag to only add the first $N$ elements from the database.

Here is an example of how it should look like.

places:
  - "~"
  - "~/Documents/"
  - "~/Documents/mnt/"
  - "~/Documents/phd/"
  - "~/Documents/projects/"

which is intended to be the list of the common places you visit in your system. This information is used by the sessionizer to know where to look

Configuration file

tmux sessions are launched by parsing a configuration file called grem.yaml that is intended to be placed on your project's root. If no file is found, it will default to a single window-pane setup.

See the templates directory for some examples. Here are a few notes of the keywords

session

• name: the name of the session
• windows: list of windows to open

windows

• name: the name of the window
• layout: layout to use. Must match tmux window layouts or null to do nothing.
• panes: list of panes to split

panes

• cwd: Working directory for the pane. Assumed to be relative to the project's root.
• command: command or list of commands to execute in the current pane. They are executed sequentially.

Usage

There are two basic ways to launch a session:

1. Run gremux, type your project's directory and hit <enter>. This will use the project's grem.yaml if available, otherwise, it will default to a generic one window/panel default.
2. If you are alredy somewhere, run

gremux config up --source /path/to/grem.yaml

if no --source is provided, it defaults to pwd

To attach to an already running tmux session interactively, run

gremux attach

To use tmux's default attach behavior directly, run

gremux attach --last

Template Workflow

Save the current project's grem.yaml as a reusable template:

gremux config save NAME

Bring that template into another project:

gremux config use NAME

Or choose one interactively:

gremux config use --interactive

List available templates:

gremux config list

When saving, session.name is rewritten to the template name. When using a template, session.name is rewritten to the current directory name.

Other Useful Commands

• To see the configuration that is going to be used, run

gremux config show

• To create the default configuration under ~/.config/gremux/default.yaml

gremux config create --source default

• To open ~/.config/gremux/ in your editor

gremux config edit

This uses the editor defined by $EDITOR.