Skip to content
lumenshellPublic

About

A fast, GPU-rendered terminal for Linux and macOS, with shell integration and plugins you can write in any language.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Lumen's icon: a glowing prompt

Lumen

A GPU-rendered terminal for Linux and macOS. It has tabs, split panes, shell integration, and plugins you can write in any language.

It's a native app, not a webview: no Electron, no browser engine underneath. Every glyph is drawn straight to the GPU.

Lumen with four tabs and three panes: a shell in a web shop project where npm test failed (its prompt marked in red) and then passed, a Vite dev server, and lumen campfire burning. The tabs carry badges: a green 128 on tests, a blue web-1.staging on deploy, and 3 to do on notes

Install

curl -fsSL https://lumenshell.dev/install | sh

It installs for your user, without sudo, on Linux (x86_64 and arm64) and macOS. Run it again to update.

On macOS you can use Homebrew instead:

brew install --cask lumenshell/tap/lumen

To uninstall, pick a version, or build from source, see Installing Lumen.

What you get

  • Tabs and split panes. Drag tabs to reorder them and drag the gaps to resize splits. Focus Mode zooms one pane. Every window, tab and split comes back next launch.
  • A quick terminal. It drops down from the top of the screen on one key, from any app, and hides again with its shells still running. More
  • Your shell, understood. Jump between commands, copy the last command's output, and spot failed commands by their red mark. Get a notification when a long command finishes while you're elsewhere. More
  • One palette for everything. Ctrl+Shift+P (⌘⇧P) fuzzy-searches every action, theme and plugin command.
  • Select and copy without the mouse. Move over the screen and scrollback with vi keys. More
  • Scripts that drive it. lumen msg opens tabs and splits, types into panes, reads their screens and streams events. More
  • Plugins in any language. Four come built in, from command history to SSH hosts, and more install from the registry, like a pomodoro timer. More
  • Themes for the whole window. 24 built in, from Rosé Pine, Catppuccin and Tokyo Night to Gruvbox, Nord and Solarized, 8 of them light. Each recolours the terminal and the chrome around it. Add your own, or use any Ghostty theme file. More

It also handles CJK input methods, the kitty keyboard protocol, clickable links, mouse reporting for vim and tmux, and colour emoji. See everything Lumen does.

Screenshots

Tabs with badges and colours, set by plugins and scripts: a pomodoro countdown, a staging server, what's left to do.

The tab bar: shop with three panes, tests with a green 128 badge, deploy with a blue web-1.staging badge, and notes badged 3 to do

Command palette: every action, theme and plugin command, fuzzy-searched, with its shortcut.

The command palette over a git log, filtered to split: Split Right and Split Down with their shortcuts
Find in scrollback, with every match highlighted.

A git log with file stats and the find bar searching for checkout: 6 of 6 matches highlighted
Keyboard select mode: move with vi keys and select by character, line or block.

A failed test run with two lines selected in keyboard select mode, and a hint saying y copies and Esc cancels
Pomodoro Timer, from the plugin registry: a big countdown in a strip under your work, with the time on the tab.

A git log above a pomodoro pane counting down from 25 minutes, with the countdown on the tab
Plugin panes: a todo list drawn by a plugin, beside your shell, with what's left on the tab.

A git log beside a todo list pane: one item ticked off and three left, with 3 to do on the tab
Plugins: turn plugins on and off, install and update them, and change their settings, all from one tab.

The plugin manager in a tab of its own: installed plugins on the left, the todo plugin selected and on, its description and permissions on the right
watch_pane.py, an example script: watch in a pane of its own, with changes highlighted.

A shell above a watch pane rerunning a status script every second, with the changed time highlighted
lumen campfire: a pixel-art fire in a pane, for cold coding sessions.

A shell with a passing test run beside a pane with a pixel-art campfire, its sparks drifting up
Rosé Pine Dawn, the light theme: every theme recolours the window around the terminal too.

The main layout in a light theme: a shell with test runs beside a Vite dev server, and tabs with badges

The keys to know

Action Linux macOS
Command palette Ctrl+Shift+P ⌘⇧P
New tab Ctrl+T ⌘T
Split right / down Ctrl+Shift+D / E ⌘D / ⌘⇧D
Close pane Ctrl+Shift+W ⌘W
Move between panes Ctrl+Arrows ⌘Arrows
Find in scrollback Ctrl+Shift+F ⌘F
Prev / next command Ctrl+Shift+↑ / ↓ ⌘⇧↑ / ⌘⇧↓

The rest are in Keyboard. You can change any of them in the config.

Config

Settings live in ~/.config/lumen/config.toml. Lumen writes it, with comments, the first time it runs, and applies your changes the moment you save.

theme = "Tokyo Night"
font-size = 14
background-opacity = 0.9

[keys]
ctrl-t = "none"   # give Ctrl+T back to the shell

Every setting and key binding is in Config.

Scripting

Inside a Lumen pane, lumen msg acts on that pane:

p=$(lumen msg split right --run 'npm run dev')   # prints the new pane's id
lumen msg tab-style --badge prod --color red
lumen msg watch command-finished                 # events as JSON lines

Scripting covers every command, the events and the JSON-RPC protocol. examples/ has ready-made scripts.

Plugins

Choose Plugins in the palette to turn on the built-in plugins, and to find, install, update and configure other people's from the registry. Each one shows what it does and what it's allowed to do before you approve it. The same works from a terminal with lumen plugins:

lumen plugins search git
lumen plugins install owner/name

Installing shows what a plugin may do and asks first. lumen plugins help lists update, remove, list, on and off, and publishing explains how to share your own.

To write your own in Python, use lumen_plugin. It comes with Lumen, so there's nothing to install:

from lumen_plugin import Plugin

app = Plugin()

@app.command("Switch Git Branch", keys="alt-b")
async def switch(pane):
    branch = await app.pick(["main", "dev"], placeholder="Switch to…")
    if branch:
        await pane.run(["git", "switch", "--", branch])   # a list is quoted for the shell

app.run()

Two extras

lumen info shows your system beside a flickering flame in your theme's colours. lumen campfire fills a pane with a crackling fire, for cold coding sessions. See Commands.

Documentation

Guide Covers
Installing Lumen Installer options, Homebrew, release files, building from source
Features Everything Lumen does
Keyboard All shortcuts, the find bar, the palette, keyboard select mode
Config Every setting and key binding
Quick terminal Setting it up on X11, Wayland and macOS
Shell integration What it adds, how it loads, using it over SSH
Commands lumen info and lumen campfire
Scripting lumen msg, events and the socket protocol
Built-in plugins The seven plugins that come with Lumen
Plugin guide Writing plugins in Python
Plugin protocol Writing plugins in any language, and permissions
Files and session Where Lumen keeps things, and its environment variables
Working on Lumen Building, tests, source layout, releasing

License

Lumen is available under either the MIT License or the Apache License 2.0, at your option. Unless you say otherwise, anything you contribute is offered under the same terms.

The bundled fonts, JetBrains Mono and Inter, keep their own license, the SIL Open Font License (JetBrains Mono, Inter).

About

A fast, GPU-rendered terminal for Linux and macOS, with shell integration and plugins you can write in any language.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages