Lumen

Terminal plugins and scriptable terminals

How kitty, WezTerm, iTerm2 and Lumen let you extend the terminal with your own code, and what each approach is good for.

Updated

Terminal plugins let you add commands, react to events and drive the terminal from code. Four terminals take this seriously. kitty has kittens, small Python programs plus a remote control API. WezTerm is configured and extended in Lua, with plugins loaded from Git. iTerm2 has a Python API for scripts on macOS. Lumen runs plugins in any language and has lumen msg for scripting from the shell. Alacritty has no plugin system. Ghostty has none either, though on macOS it now has AppleScript support (labelled a preview in 1.3) and Shortcuts actions.

Terminal plugins compared

TerminalLanguageExtension modelDrive it from the shell
kittyPythonKittens run in an overlay; handle_result runs inside kittykitten @ remote control
WezTermLuaConfig is code; event handlers; plugins via wezterm.plugin.requirewezterm cli
iTerm2PythonScripts using the iTerm2 Python API, run from the Scripts menu or at launchThrough the Python API
LumenAnyPlugins as separate programs with approved permissionslumen msg

kitty kittens

A custom kitten is a Python file in your kitty config folder, run with a mapping such as map ctrl+k kitten mykitten.py. Its main() runs in an overlay window and can read the screen or scrollback; its handle_result() runs inside kitty with access to every window. kitty's own tools, such as its themes picker and SSH helper, are kittens too. For scripts outside kitty, kitten @ sends remote control commands: open windows, send text, change colours. It's a lot of reach, but tied to kitty's Python internals.

WezTerm and Lua

WezTerm's config file is a Lua program. You can register event handlers, build the tab bar's text, define key bindings that run functions, and pull in plugins: wezterm.plugin.require("https://github.com/...") clones a Git repository of Lua code. Updates are manual, with wezterm.plugin.update_all(). If you like having your terminal as a program, this is the most flexible model. See WezTerm vs kitty for how the two compare beyond scripting.

The iTerm2 Python API

On macOS, iTerm2 exposes windows, tabs, sessions, profiles and the status bar through an async Python library. You turn the API on in iTerm2's settings, then write scripts that run from the Scripts menu or start with the app. People use it for custom status bar components, reacting to new sessions, and arranging windows. It's the most complete API of the macOS terminals; iTerm2 alternatives covers what you give up by leaving it.

Lumen plugins

A Lumen plugin is a folder in ~/.config/lumen/plugins/<name>/ holding a plugin.toml and a program. The program can be written in any language. Lumen starts it, and restarts it if it crashes. Plugins can:

  • add commands to the command palette and key bindings,
  • show pickers,
  • draw panes of their own,
  • put badges and colours on tabs.

Each plugin only gets the permissions you approve. Python plugins get a lumen_plugin module built in (Python 3.8 or later, standard library only), so there's nothing to install. The manifest fields and the module's API are in the plugin docs.

Turn plugins on in config.toml and bind their commands like any other action:

plugins = ["git-branch", "pomodoro"]

[keys]
alt-g = "plugin:git-branch:switch"

The built-in plugins

Seven plugins ship with Lumen, all off until you turn them on in the Plugin Gallery: Recent Directories, Command History (search every command from every pane, rerun the last failure), Switch Git Branch, SSH to Host (from ~/.ssh/config), Projects & Tasks (open a project's tabs, splits and dev tasks from .lumen-layout.toml), Build Status (puts something like ✓ cargo test · 12s in the tab title) and Pomodoro Timer. They are a good place to read example code; see the built-in plugin docs.

Scripting Lumen with lumen msg

For one-off scripts, you don't need a plugin. Set socket-api = true and lumen msg talks to the running app over a local socket. It can open tabs and splits, type into a pane (send-text), read a pane's screen (read-screen), set tab titles, badges and colours, send notifications, run any action, and stream events as JSON.

This short Python program watches for finished commands and marks the tab green or red. It uses only the standard library and lumen msg, so you can run it from a shell, or make it the program in a plugin folder so Lumen keeps it running:

#!/usr/bin/env python3
# Badge the tab by the result of each command.
import json
import subprocess

watch = subprocess.Popen(
    ["lumen", "msg", "watch", "command-finished"],
    stdout=subprocess.PIPE,
    text=True,
)

for line in watch.stdout:
    event = json.loads(line)
    # e.g. {"event": "command-finished", "command": "npm test", "exit": 0}
    passed = event["exit"] == 0
    subprocess.run([
        "lumen", "msg", "tab-style",
        "--badge", "ok" if passed else "fail",
        "--color", "green" if passed else "red",
    ])

The command-finished events come from shell integration, so they work in bash, zsh and fish without any setup. The scripting docs list every lumen msg command and its options.

Which one suits you

If you want to reshape the whole terminal in code, WezTerm's Lua is the deepest. If you live in kitty and write Python, kittens are well documented and fast to write. On macOS, iTerm2's Python API covers more of the app than anything else. Lumen suits people who want to write extensions in the language they already use, keep them isolated behind permissions, and script tabs from the shell; it is newer, so its plugin ecosystem is small. For a broader view, see the best terminal emulators and how Lumen uses tab badges and session restore.

Questions

Which terminal has the best plugin support?

WezTerm's Lua config and plugins are the most flexible, kitty's kittens are the easiest way to add Python tools, and iTerm2 has the fullest API on macOS. Lumen accepts plugins in any language.

What is a kitty kitten?

A small Python program that kitty runs in an overlay window, with a hook that runs inside kitty itself. kitty's built-in tools, like its theme picker, are kittens.

Can I write Lumen plugins in Python?

Yes. Python plugins get the lumen_plugin module built in, needing Python 3.8 or later and only the standard library. Any other language works too.

Does Ghostty have plugins?

Not as of late 2026. Ghostty is configured with a plain config file. On macOS it can be scripted with AppleScript (a preview since 1.3), but there is no cross-platform plugin system like WezTerm's or Lumen's.

Try Lumen

Free and open source, for Linux and macOS. Copy the command for your system and paste it into a terminal.

curl -fsSL https://lumenshell.dev/install | sh
brew install --cask lumenshell/tap/lumen