Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fresh2dev/zellij-autolock
autolock Zellij when certain processes open.
https://github.com/fresh2dev/zellij-autolock
zellij-plugin
Last synced: 4 days ago
JSON representation
autolock Zellij when certain processes open.
- Host: GitHub
- URL: https://github.com/fresh2dev/zellij-autolock
- Owner: fresh2dev
- License: mit
- Created: 2024-05-13T22:52:39.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2024-05-29T03:49:11.000Z (5 months ago)
- Last Synced: 2024-08-01T16:49:34.954Z (3 months ago)
- Topics: zellij-plugin
- Language: Rust
- Homepage:
- Size: 32.2 KB
- Stars: 34
- Watchers: 1
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# zellij-autolock
*zellij-autolock* is an experimental Zellij plugin that automatically switches between Zellij's "Normal" and "Locked" modes depending on the process running within the focused Zellij pane.
I built *zellij-autolock* in pursuit of seamless navigation between Zellij panes and Vim windows. It works well for Vim, Neovim, and with other CLI applications that use keymaps that conflict with Zellij's keymaps including Helix, FZF, and more.
> Note: When using with [Neo]vim, you'll also want to install this Vim plugin: [***zellij.vim***](https://github.com/fresh2dev/zellij.vim)
## Demo
Here is a demonstration of how you can seamlessly navigate through Zellij panes running Vim, Neovim, Helix, FZF, and more.
This page does not support webm video playback.
Click here to watch the demo recording.
Open full screen demo recording.
Notice how the Zellij mode ( "Normal" or "Locked" in the top-right corner ) automatically toggles depending which process is running within the focused Zellij pane. This allows you to use the same mappings ( `Ctrl+h/j/k/l` ) to navigate between Zellij panes, Vim windows, FZF results, and more.
## Install
Download the wasm file from the [releases page](https://github.com/fresh2dev/zellij-autolock/releases). Save it to your Zellij config path (e.g., `~/.config/zellij/plugins/zellij-autolock.wasm`). You will reference this path when defining the plugin in your Zellij config.
## Config
> Note: Zellij >= 0.40.1 is required.
This is a "headless" Zellij plugin; it has no UI. It is activated by pressing the `Enter` key in Zellij's "Normal" mode. Once activated, this plugin responds to Zellij events ( `TabUpdate` and `PaneUpdate` ) by examining the process running within the focused Zellij pane. If the running process is in either list `trigger` or `watch_trigger`, Zellij is then set to "Locked" mode. Otherwise it is unlocked (i.e., set to "Normal").
I use the following Zellij config to intercept the "Enter" key, pass it through, then launch this plugin -- (an excerpt from [my dotfiles](https://github.com/fresh2dev/dotfiles)):
```kdl
plugins {
// Define the "autolock" plugin.
autolock location="file:~/.config/zellij/plugins/zellij-autolock.wasm" {
triggers "nvim|vim" // Lock when any open these programs open. They are expected to unlock themselves when closed (e.g., using zellij.vim plugin).
watch_triggers "fzf|zoxide|atuin" // Lock when any of these open and monitor until closed.
watch_interval "1.0" // When monitoring, check every X seconds.
}
//...
}
keybinds {
normal {
bind "Enter" { // Intercept `Enter`.
WriteChars "\u{000D}"; // Passthru `Enter`.
MessagePlugin "autolock" {}; // Activate the autolock plugin.
}
// Note: You may want to bind/intercept/relay other keys to activate this plugin,
// like `Ctrl+r` which opens shell history in Atuin / FZF. For example:
// bind "Ctrl r" { // Intercept `Ctrl+r`.
// WriteChars "\u{0012}"; // Passthru `Ctrl+r`
// MessagePlugin "autolock" {}; // Activate the autolock plugin.
// }
}
//...
shared_except "locked" {
// Put keybindings here if they conflict with Vim or others.
bind "Ctrl h" {
MoveFocus "Left";
// OR: MoveFocusOrTab "Left";
}
bind "Ctrl l" {
MoveFocus "Right";
// OR: MoveFocusOrTab "Right";
}
bind "Ctrl j" {
MoveFocus "Down";
// OR: MoveFocusOrTab "Down";
}
bind "Ctrl k" {
MoveFocus "Up";
// OR: MoveFocusOrTab "Up";
}
// bind "Ctrl d" { HalfPageScrollDown; }
// bind "Ctrl u" { HalfPageScrollUp; }
// bind "Ctrl f" { PageScrollDown; }
// bind "Ctrl b" { PageScrollUp; }
//...
}
//...
}
```
The `triggers` setting allows a pipe-separated (`|`) list of CLI commands that will trigger Zellij's "Locked" mode.
This plugin **can lock** Zellij when it encounters one of these commands, but it **cannot unlock** when the command exits. So, commands provided to `triggers` are expected to unlock Zellij on close. In the context of [Neo]vim, this is made possible with the Vim plugin [zellij.vim](https://github.com/fresh2dev/zellij.vim).
The `watch_triggers` setting accounts for CLI commands that have no way of unlocking Zellij on close. When *zellij-autolock* encounters one of these commands, it puts Zellij into "Locked" mode and starts a timer that evaluates every `` seconds. When the command exits, Zellij will unlock after the timer performs a cycle. This is intended for transient commands that benefit from `Ctrl+h/j/k/l` nav, like `fzf`, `zoxide`, and `atuin`.
## Troubleshooting
If you experience issues with the plugin, first try opening a fresh Zellij session. If that doesn't work, clear the Zellij cache and restart Zellij (`rm -rf ~/.cache/zellij` on Linux; `~/Library/Caches/org.Zellij-Contributors.Zellij` on macOS)
[Zellij logs](https://zellij.dev/documentation/plugin-api-logging) are viewable here (on Linux):
```sh
tail -f /tmp/zellij-$(id -u)/zellij-log/zellij.log
```
## Future
Today, this plugin uses Zellij CLI commands to determine the process running within the focused Zellij pane (there is a report of terminal flashing [#3](https://github.com/fresh2dev/zellij-autolock/issues/3) related to this implementation). When it is possible to use the Zellij API to make the distinction, I plan to refactor.
This project is experimental and exists as a proof-of-concept. This is my first round of writing a Zellij plugin, or a project in Rust for that matter. If this project were to thrive, it would not be without community contributions. If this plugin solves [the Zellij / Vim navigation problem (#967)](https://github.com/zellij-org/zellij/issues/967), I dream that it'd just be baked into the Zellij project.
## Shoutouts
- [zellij-org/zellij](https://github.com/zellij-org/zellij)
- [hiasr/vim-zellij-navigator](https://github.com/hiasr/vim-zellij-navigator)
- [christoomey/vim-tmux-navigator](https://github.com/christoomey/vim-tmux-navigator)
- [dj95/zjstatus](https://github.com/dj95/zjstatus)