Tmux Grimoire

A lightweight tmux plugin for summonable popup shells, aka shpells, driven by custom scripts.

Quickstart

Install with TPM:

set -g @plugin 'navahas/tmux-grimoire'

Press prefix + I to install.

Note: If you’d rather install manually, see Manual Installation below.

Minimal config to get started:

# Enable plugin
set -g @plugin 'navahas/tmux-grimoire'

# Global appearance
set -g @grimoire-title   ' grimoire '
set -g @grimoire-color   '#c6b7ee'
# Optional overrides:
# set -g @grimoire-width  '80%'
# set -g @grimoire-height '30%'
# set -g @grimoire-position 'bottom-center'

# Custom shpells
bind-key -T prefix q run-shell "custom_shpell standard dev"
bind-key -T prefix G run-shell "custom_shpell ephemeral gitlog \"git log --oneline --graph --decorate --all\""
set -g @shpell-gitlog-color    '#e3716e'
set -g @shpell-gitlog-position 'right'
set -g @shpell-gitlog-width    '50%'
set -g @shpell-gitlog-height   '100%'

Now hit:

• prefix + q —> your dev shell
• prefix + G —> ephemeral gitlog shell

Default keybinds:

prefix + f    # Opens the main shpell
prefix + F    # Opens an ephemeral shpell
prefix + C    # Kills the current shpell window

---

Manual Installation

git clone https://github.com/navahas/tmux-grimoire.git ~/.tmux/plugins/tmux-grimoire

Add to ~/.tmux.conf:

run-shell ~/.tmux/plugins/tmux-grimoire/grimoire.tmux

---

Configuration

Global Options

# Keybindings (defaults: f, F, C)
set -g @grimoire-key "f"
set -g @ephemeral-grimoire-key "F"
set -g @grimoire-kill-key "C"

# Appearance
set -g @grimoire-title ' 󱥭 ' # If you have a nerdfont to use icons
set -g @grimoire-color '#6c6c65'
set -g @grimoire-width '80%'
set -g @grimoire-height '70%'
set -g @grimoire-position 'center'

# Custom shpells path
set -g @grimoire-path '$HOME/.config/grimoire' # default location

Position Options

top-left    | top-center    | top-right
bottom-left | bottom-center | bottom-right
left        | right         | center

---

Custom Shpells

Create custom popup shells (shpells) to launch any script, CLI tool, or command.

Binding Syntax

bind-key -T prefix <key> \
  run-shell "custom_shpell <standard|ephemeral> <shpell-name> '<command>' [--replay]"

• standard | ephemeral: Choose either a persistent shell (standard) or close after use (ephemeral).
• shpell-name: Custom label identifier (avoid spaces), e.g. logs, build, test-log, unit_tests.
• command: Shell command or script path to be executed; omit for a blank shell.
• --replay (optional): re-run only when idle (for tasks like builds).

Important

By default, commands only run once when a custom shpell is triggered. To support repeated executions (e.g., running cargo build again), use the --replay flag.

Smart Replay: If --replay is set, the command is only re-sent if the shell is idle, ensuring that active processes aren't interrupted.

Tip

Check out the grimoire repo for a collection of reusable scripts (shpells).

Bindings Examples:

bind-key -T prefix E run-shell "custom_shpell standard personal-shpell"
bind-key -T prefix b run-shell "custom_shpell standard rust-build 'cargo build' --replay"
bind-key -T prefix W run-shell "custom_shpell standard my-bar '$HOME/.config/foo/bar.sh' --replay"
# Using the scripts inside @grimoire-path '$HOME/.config/grimoire'
bind-key -T prefix R run-shell "custom_shpell ephemeral test 'sphell/test.sh'"
bind-key -T prefix Q run-shell "custom_shpell ephemeral test-logs 'tail -f /var/log/syslog'"

Per-Shpell Options

Override size, color, title, position per shpell.

set -g @shpell-<shpell-name>-color
set -g @shpell-<shpell-name>-position
set -g @shpell-<shpell-name>-width
set -g @shpell-<shpell-name>-height

All unspecified fallback to global @grimoire-* values.

Examples:

# shpell-name: dev
bind-key -T prefix q run-shell "custom_shpell standard dev"
set -g @shpell-dev-color '#c2b3e9'
set -g @shpell-dev-position 'top-right'
set -g @shpell-dev-width '100%'
set -g @shpell-dev-height '50%'

# shpell-name: gitlog
bind-key -T prefix G run-shell "custom_shpell ephemeral gitlog \"git log --oneline --graph --decorate --all\""
set -g @shpell-gitlog-color '#d98870'
set -g @shpell-gitlog-position 'bottom-left'
set -g @shpell-gitlog-width '50%'
set -g @shpell-gitlog-height '100%'

Recommended Keys for Custom Shpells

Q, W, E, R, T, Y, U, H, M, F, G

These keys are generally unbound in tmux and offer a smooth developer workflow.

Friendly Reminder: Uppercase bindings (like Q) require holding Shift, e.g. prefix + Shift + Q.

---

Advanced

Window Position

The following bind allows to move windows within your tmux session.

bind -r N swap-window -t -1 \; select-window -t -1
bind -r M swap-window -t +1 \; select-window -t +1

Splits Support

Shpells respect existing splits. For best layouts, explicitly size/position or use full-width examples:

---

Alternative

If you are looking for a single feature-rich floating shell implementation, consider tmux-floax.

License

MIT