gremux 0.1.0

A declarative tmux session manager

gremux

A declarative tmux session manager.

[!NOTE] This project is very early in development. Only a few features are implemented, and there is 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 in a per-project basis
• tmux-sessionizer, inspired by ThePrimeagen's script.

For a list of TODOs, see the roadmap

Installation

This project is in very early stages of development, there is no proper way for installation other than a local python package.

1. Create a (global) virtual environment where your shell defaults into.
2. Install the repository with pip

pip install gremux

3. Install fzf from your package manager.

Run gremux to open the sessionizer.

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: 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

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