README.md in zach/leaf
leaf
A small, no-frills terminal emulator for macOS, rendered on the GPU with wgpu. It does what vim, tmux, less and a shell need and not much else: no tabs, splits, profiles, plugins or scripting. The whole thing is ~4,000 lines of Rust meant to be read and changed.
Build and run
cargo run --release
make app # target/release/Leaf.app
make install # copies it to /Applications
The icon is the leaf from Yarndings 20
(SIL Open Font License). make icon FONT=path/to/font.ttf GLYPH=h redraws
macos/Leaf.icns from any glyph of any font.
What it supports
- 16, 256 and 24-bit color; bold, italic, dim, underline, strikethrough, inverse
- Any installed font by family name (or a font file path), with real bold/italic faces and automatic fallback for CJK, emoji and symbols
- Programming ligatures (
->,!=,>=... in fonts like Berkeley Mono, Fira Code or JetBrains Mono), via text shaping - Combining characters (accents, Vietnamese tone marks, emoji variation selectors)
- Box-drawing, block and powerline characters drawn by leaf itself, so vim splits, tmux borders and statuslines join seamlessly
- Alternate screen, scroll regions, application cursor keys, bracketed paste,
focus events, synchronized output, cursor shape changes (vim's
t_SI/t_EI) - Mouse reporting (vim
mouse=a, tmux), with Shift held to select instead - Scrollback, mouse/trackpad scrolling, click-drag (past the top or bottom to scroll) / double-click (word) / triple-click (line) selection
- Text re-wraps when the window is resized
- Blinking cursor (programs like vim can switch blinking and shape)
- OSC 52 clipboard writes (e.g. vim/tmux yanking over ssh), window titles
- Multiple windows; a new window opens in the directory the current one's shell is in
- Scrollback search (Cmd+F)
- Cmd+click to open URLs
- Shell integration (OSC 133): jump between prompts, copy a command's output, and a notification when a long command finishes while you're in another app
- Desktop notifications from programs (OSC 9 and OSC 777)
- Separate light and dark colors that follow the system appearance, reported to programs that ask (mode 2031, as in Neovim)
- The config file is reloaded as soon as you save it
Keys
| Key | Action |
|---|---|
| Cmd+C / Cmd+V | Copy selection / paste |
| Cmd+N / Cmd+W | New window / close window |
| Cmd+, | Settings |
| Cmd+= / Cmd+- / Cmd+0 | Bigger / smaller / default font size |
| Cmd+K | Clear scrollback |
| Cmd+F | Search the scrollback (see below) |
| Cmd+click | Open the URL under the mouse (hold Cmd to see it underlined) |
| Cmd+Shift+↑ / Cmd+Shift+↓ | Jump to the previous / next prompt (needs shell integration) |
| Cmd+Shift+C | Select and copy the last command's output (needs shell integration) |
| Cmd+← / Cmd+→ | Start / end of line |
| Option+← / Option+→ | Back / forward a word |
| Cmd+Backspace / Option+Backspace | Delete to start of line / previous word |
| Cmd+Delete / Option+Delete | Delete to end of line / next word |
| Cmd+↑ / Cmd+↓ | Scroll back / forward a line |
| Cmd or Shift + PageUp / PageDown | Scroll back / forward a page |
| Cmd or Shift + Home / End | Top / bottom of scrollback |
| Option+key | Sent as Meta (Esc+key); see option_as_alt |
| Cmd+drag | Move the window from anywhere in it |
The line-editing keys work like iTerm's "Natural Text Editing" preset: they send the shell's (readline/zsh) bindings Ctrl-A, Ctrl-E, Ctrl-U, Ctrl-W, Ctrl-K, Esc-b, Esc-f and Esc-d, as iTerm does. In vim's insert mode only the Backspace ones (Ctrl-U, Ctrl-W) mean the same thing.
Mouse wheel scrolls the scrollback; in full-screen programs without mouse support (less, man) it sends arrow keys instead.
Search
Cmd+F opens a search bar over the bottom row. Typing searches as you go, ignoring case unless the query has a capital letter. The current match is selected, so Cmd+C copies it.
| Key | Action |
|---|---|
| Enter, ↑ or Cmd+G | Previous (older) match |
| Shift+Enter, ↓ or Cmd+Shift+G | Next match |
| Cmd+V | Paste into the query |
| Option+Backspace | Clear the query |
| Esc | Close the bar, leaving the match selected |
Shell integration
Prompt jumping, copying a command's output and "command finished" notifications need the
shell to mark its prompts. For zsh, add this to ~/.zshrc, after any prompt theme:
[[ $TERM_PROGRAM == leaf ]] && source /Applications/Leaf.app/Contents/Resources/leaf.zsh
(make app puts shell/leaf.zsh there.) It sends OSC 133 marks and reports the working
directory with OSC 7. New windows open in the current directory without it, since leaf can
also ask the OS where the shell is.
Configuration
The easiest way is leaf → Settings… (Cmd+,) in the menu bar: a window with every setting
explained, where changes apply to open windows as you make them. It writes
~/.config/leaf/config.toml for you, keeping any comments in it, and leaves out settings that
are at their defaults.
Or let an AI agent do it: leaf → Copy AI Setup Prompt copies a prompt (with this reference and your current config) for Claude or another coding agent. Paste it in, and the agent asks how you like your terminal and writes the file.
You can also edit ~/.config/leaf/config.toml by hand. Everything is optional; these are the
defaults:
[font]
family = "Menlo" # family name, or a path like "~/fonts/Foo.ttf"
size = 14.0 # points
line_height = 1.0 # multiplier
fallback = [] # extra families for missing glyphs, e.g. ["Symbols Nerd Font Mono"]
builtin_box_drawing = true # draw ─│┌ ▀█ etc. instead of using the font
ligatures = true
[window]
columns = 100
rows = 30
padding = 6.0 # points
option_as_alt = "both" # "both", "left", "right" or "none" (Option types special characters)
decorations = "buttonless" # "buttonless", "transparent", "none" or "full" (see below)
[colors]
foreground = "#d4d4d4"
background = "#1c1c1c"
cursor = "#d4d4d4"
# cursor_text = "#1c1c1c" # text under the block cursor; defaults to background
selection = "#3e4a5c"
search_match = "#5a4a24" # other search matches; the current one uses `selection`
palette = [
"#1c1c1c", "#e06c75", "#98c379", "#e5c07b", "#61afef", "#c678dd", "#56b6c2", "#c8c8c8",
"#5c6370", "#ff7a85", "#b5e890", "#ffd88a", "#82c4ff", "#de96f0", "#7ad4de", "#ffffff",
]
[terminal]
# shell = "/bin/zsh" # defaults to $SHELL, run as a login shell
args = []
# working_directory = "~" # defaults to $HOME
scrollback = 10000
cursor_style = "block" # "block", "beam" or "underline"
cursor_blink = true
scroll_multiplier = 3.0
copy_on_select = false
notifications = true # show OSC 9 / OSC 777 notifications while the window is in the background
notify_after_seconds = 10.0 # with shell integration, notify when a command this long finishes; 0 = off
Saving the file applies it to open windows straight away: fonts, colors, padding, scrollback,
cursor and option_as_alt. The window size, decorations and the shell apply to new windows.
If the file has a mistake, leaf keeps the old settings and shows a notification saying why.
Light and dark mode
Add [colors.light] and/or [colors.dark] to follow the system appearance, switching when it
changes. Each takes any of the [colors] keys and falls back to [colors] for the rest:
[colors.light]
foreground = "#383a42"
background = "#fafafa"
cursor = "#383a42"
selection = "#d0d8e8"
search_match = "#f0e0a0"
palette = [
"#383a42", "#e45649", "#50a14f", "#c18401", "#0184bc", "#a626a4", "#0997b3", "#a0a1a7",
"#696c77", "#e45649", "#50a14f", "#c18401", "#0184bc", "#a626a4", "#0997b3", "#fafafa",
]
Changing colors (by reloading or by switching mode) resets any colors a program changed with OSC 4/10/11/12.
decorations picks the window frame on macOS:
buttonless: no visible title bar or buttons; drag the window by the strip along its top (double-click it to zoom)transparent: likebuttonless, with the traffic-light buttonsnone: no title bar or border at all, square corners; move the window with Cmd+dragfull: the standard title bar (dark when the background is dark)
Finding your way around
| File | What's in it |
|---|---|
src/main.rs | Windows, the event loop, keyboard shortcuts, mouse and selection |
src/term.rs | Terminal state and escape-sequence handling (the xterm subset) |
src/input.rs | Key and mouse events → bytes for the program |
src/renderer.rs | wgpu setup, glyph atlas, building each frame |
src/shader.wgsl | The one shader: instanced rects and glyphs |
src/font.rs | Font lookup, fallback, shaping and rasterizing (swash) |
src/boxdraw.rs | Procedurally drawn line and block characters |
src/pty.rs | Starting the shell on a pseudo-terminal |
src/config.rs | Config file and defaults |
src/notify.rs | Desktop notifications and opening links |
src/settings.rs | The Settings window's link to the config file, and the AI setup prompt |
src/menu.rs | leaf's items in the macOS app menu |
macos/Settings.swift | The Settings window (SwiftUI), built by build.rs as leaf-settings |
shell/leaf.zsh | Shell integration for zsh |
Things deliberately left out: tabs and splits (use tmux), IME composition, images, OSC 8 hyperlinks (plain URLs are still clickable), and the kitty keyboard protocol.
cargo test runs the terminal-emulation and key-encoding tests.
License
MIT, see LICENSE. The app icon is drawn from the Yarndings 20 font, which is under the SIL Open Font License.