Lumen, a terminal emulator for macOS
A free, open-source terminal emulator for Mac, written in Rust and drawn on the GPU. Here's what it does, how to install it, and how it compares.
Lumen is a terminal emulator for macOS and Linux. On a Mac it's a universal app (Apple silicon and Intel), written in Rust, with its interface drawn by GPUI, the GPU UI framework from the Zed editor. The terminal emulation itself comes from the alacritty_terminal crate, the same core Alacritty uses. It isn't Electron or a webview: every glyph is drawn on the GPU.
It's free and open source under MIT or Apache 2.0, at version 1.0, and much newer and smaller than iTerm2 or Ghostty, with one main author. If you need a mature macOS terminal emulator with years of edge cases ironed out, those are safer picks. If you want shell-aware features, session restore and plugins in a native app, read on.
Install the macOS terminal emulator
With Homebrew:
brew install --cask lumenshell/tap/lumen
Or with the install script, which installs for your user only, needs no sudo, and updates Lumen when you run it again:
curl -fsSL https://lumenshell.dev/install | sh
First launch: notarization
The macOS app isn't notarized by Apple yet, so Gatekeeper will stop it the first time. Right-click Lumen in Applications and choose Open, then confirm. On recent macOS versions that option may not appear; open System Settings > Privacy & Security and click Open Anyway next to the message about Lumen. You only do this once. Full steps are in the install docs.
What Lumen does on a Mac
Tabs, splits and windows
Tabs live in a custom title bar and show how many panes each holds. Drag to reorder, double-click or press Cmd+, to rename. A new tab opens in the folder you were in. Split right with Cmd+D and down with Cmd+Shift+D, drag the gaps to resize, and double-click a gap to even it out. Cmd+Arrows moves between panes, and Focus Mode (Cmd+Shift+Enter) zooms one pane to fill the tab. More in our guide to split terminals on Mac.
Session restore
Quit and reopen, and every window, tab, split, pane size, folder, tab name and window position comes back. The running programs don't: you get the layout and folders, not a resumed vim session.
Shell integration for zsh, bash and fish
zsh is the default shell on macOS, and Lumen's shell integration loads into it automatically. You get:
- A grey or red mark beside each prompt for success or failure, with failed prompts tinted red.
- Marks on the scrollbar for every command, red for failures; click one to jump there.
- Cmd+Shift+Up/Down to jump between commands, and Cmd+Shift+O to copy the last command's output.
- A macOS notification when a command that ran for 10 seconds or more (set with
notify-after) finishes while you're in another app, plus a green or red dot on its tab.
Over SSH you source the integration script on the remote host to get the same marks.
Quick terminal
Set quick-terminal-key and a key brings a Lumen window forward from any app, and hides it again with its shells still running. On macOS this is an ordinary window, not a full-width drop-down that slides over everything. If you want the drop-down behaviour, iTerm2's hotkey window and Ghostty's quick terminal do that. See quick terminals.
Keyboard, search and the palette
Cmd+F searches scrollback, with case-sensitive and regex options. Cmd+Shift+Space enters keyboard select mode, where vi keys move over the screen and scrollback and you select by character, line or block. Cmd+Shift+P opens a command palette that fuzzy-searches every action, theme and plugin command. Lumen speaks the kitty keyboard protocol, so Neovim and Helix can tell Ctrl+I from Tab.
Rendering and input
Truecolor, bold and italic, undercurl, colour emoji and wide CJK glyphs. Box-drawing and Powerline characters are drawn as shapes so prompts join up without gaps. The background can be see-through and blurred with background-opacity. CJK input methods, compose and dead keys work. URLs and OSC 8 links open with Cmd+click.
Plugins and scripting
Seven built-in plugins, off until you turn them on in the Plugin Gallery, add things like Switch Git Branch, SSH to Host from ~/.ssh/config, Recent Directories and Command History. You can write your own in any language. lumen msg opens tabs and splits, types into panes, reads their screens and streams events as JSON, so scripts can react when npm test finishes. See the plugin docs and scripting docs.
Configuration
Lumen writes a commented ~/.config/lumen/config.toml on first run. Save it and open panes update; no restart. A mistake shows in a banner and the rest of the file still applies.
theme = "Catppuccin Mocha"
font-family = "JetBrains Mono"
font-size = 14
background-opacity = 0.92
cursor-style = "beam"
[keys]
ctrl-t = "none"
There are 24 built-in themes, 8 of them light, from Rosé Pine (default), Catppuccin and Tokyo Night to Gruvbox, Nord and Solarized. You can add your own or drop in any Ghostty theme file, and a light and a dark theme can follow macOS's appearance. Any installed monospace font works, including Nerd Fonts. The config reference lists every key.
What Lumen doesn't do on macOS
- No inline images (no kitty graphics protocol or sixel). iTerm2, Ghostty, kitty and WezTerm show images.
- No tmux integration and no detach/reattach. Use tmux inside Lumen, or iTerm2 if you want
tmux -CC. - No multi-key bindings such as
ctrl-a n. - No built-in AI. You can run any agent CLI in it, of course.
- No Windows version, if you need the same terminal everywhere.
How Lumen compares with other Mac terminal emulators
| Lumen | Terminal.app | iTerm2 | Ghostty | |
|---|---|---|---|---|
| Split panes | Yes | No | Yes | Yes |
| Session restore | Layout and folders | Windows and folders | Yes | Via macOS window restore |
| Shell integration | Automatic | Basic | Install step | Automatic |
| Inline images | No | No | Yes | Yes |
| Plugins / API | Any language | AppleScript | Python | No plugins |
| Maturity | New (1.0) | Decades | Over a decade | Since 2024 |
For a longer look at all the options, see the best terminal for Mac, or alternatives to the Mac Terminal app.
Questions
Does Lumen work on Apple silicon Macs?
Yes. The macOS build is a universal app, so it runs natively on Apple silicon and on Intel Macs.
Why does macOS say Lumen can't be opened?
The app isn't notarized yet. Right-click it and choose Open, or on newer macOS versions approve it under System Settings > Privacy & Security > Open Anyway. You only need to do this once.
How do I update Lumen on a Mac?
Run brew upgrade --cask lumen if you installed with Homebrew, or run the curl install script again.
Is Lumen a replacement for iTerm2?
For many people, yes: it covers tabs, splits, a hotkey window and shell integration. It lacks iTerm2's tmux integration, triggers and inline images, so heavy users of those should stay. See iTerm2 alternatives.
Try Lumen
Free and open source, for Linux and macOS. Copy the command for your system and paste it into a terminal.