AI TL;DR
Too lazy to read? Summarize this post with:
Blog Post Publish Date: 2026/10/28
Hacking Your Zsh Terminal with Custom Widgets#
This blog post explains how to create custom Zsh widgets: shell functions bound to keyboard shortcuts through the Zsh Line Editor (ZLE). It's the Zsh version of Hacking Your Bash Terminal with Custom Widgets, and it ends with the same widget that reruns the current command every two seconds.
Understand the Basics#
ZLE (Zsh Line Editor) is the part of Zsh that handles command-line editing, the Zsh counterpart of GNU Readline in Bash. A ZLE widget is a function that ZLE runs when you press its key. You write a Zsh function, register it as a widget with zle -N, and bind it to a key with bindkey.
While a widget runs, ZLE gives it special parameters. The four main ones are:
BUFFER: the whole content of the command line.
CURSOR: the cursor position, as an offset into
BUFFER.LBUFFER: the part of the line left of the cursor.
RBUFFER: the part of the line right of the cursor.
Unlike Bash, Zsh gives you LBUFFER and RBUFFER directly, so inserting text at the cursor is as simple as LBUFFER+="text".
To see them in practice, create a function called debug-hook-variables that prints all four, register it, and bind it to Ctrl+x:
# zsh function for debugging reserved variables
function debug-hook-variables() {
echo
echo ">>> BUFFER: $BUFFER"
echo ">>> RBUFFER: $RBUFFER"
echo ">>> LBUFFER: $LBUFFER"
echo ">>> CURSOR: $CURSOR"
}
# register the function as a ZLE widget
zle -N debug-hook-variables
# check if "debug-hook-variables" are registered as widget
zle -al | grep debug-hook-variables
# define "Ctrl+x" shortcut for "debug-hook-variables" widget
bindkey '^X' debug-hook-variables
# list all widgets with shortcut defined
bindkey -L
Now type something at the prompt and press Ctrl+x. For example, with the cursor right after definitely, the output is:
$ definitely| maybe # press `Ctrl+x`
>>> BUFFER: definitely maybe
>>> RBUFFER: maybe
>>> LBUFFER: definitely
>>> CURSOR: 10
RBUFFER starts with the space after definitely, and CURSOR is 10 because definitely has 10 characters.
In the default emacs keymap,
Ctrl+xis also the prefix of several built-in bindings, such asCtrl+x Ctrl+ein many setups. BindingCtrl+xalone replaces that prefix. If you use those bindings, choose another key.
Practical Example: Repeated Command Execution#
Now a useful widget: an alternative to watch. watch runs its command in a new sh -c, so your aliases, such as kgp, aren't available (see this Stack Overflow thread). This widget runs whatever is on the command line every two seconds when you press Ctrl+x, in your current shell, so aliases work.
function repeat-command-widget() {
while true; do
clear
eval "$BUFFER"
sleep 2
done
}
zle -N repeat-command-widget
bindkey '^X' repeat-command-widget
To test it, type a command and press Ctrl+x:
kgp
### press `Ctrl+x`
### stop execution by `Ctrl+c`
kgp runs every two seconds until you press Ctrl+c, just like watch "kubectl get pods".
How to Register the Widget#
Built-in ZLE widgets only need a bindkey line. A custom widget also needs its function and the zle -N registration, so put all three in ~/.zshrc:
# ~/.zshrc
# define the function
function repeat-command-widget() {
while true; do
clear
eval "$BUFFER"
sleep 2
done
}
# register funtion as a widget
zle -N repeat-command-widget
# define Ctrl+x to execute "repeat-command-widget" command
bindkey '^X' repeat-command-widget
The Ctrl+x shortcut is then available in every new Zsh session.
Where to Go From Here#
Widgets turn any repetitive edit or command into one key press. Many Zsh plugins are widgets too: fzf binds its history, file, and directory search as ZLE widgets, and zsh-autosuggestions, which I use in my ZSH + Starship setup, works by wrapping the built-in ones.
Key Takeaways#
ZLE is the Zsh line editor. A widget is a function that ZLE runs when you press its key.
Register a function as a widget with
zle -N name, then bind it withbindkey '^X' name. Check it withzle -alandbindkey -L.Inside a widget,
BUFFERholds the command line,CURSORthe cursor offset, andLBUFFERandRBUFFERthe text left and right of the cursor.watchruns its command in a new shell, so aliases fail. A widget thatevals$BUFFERin a loop runs in your shell, so they work.Put the function,
zle -N, andbindkeyin~/.zshrc.
References#
I'm Carlos Neto, and this blog is a brain dump of my career experience. More about me on my home page. If you have questions or a different approach, contact me on LinkedIn or leave a comment below.