Files in zach/leaf

README.md 221 lines · 9.5 KB

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

KeyAction
Cmd+C / Cmd+VCopy selection / paste
Cmd+N / Cmd+WNew window / close window
Cmd+,Settings
Cmd+= / Cmd+- / Cmd+0Bigger / smaller / default font size
Cmd+KClear scrollback
Cmd+FSearch the scrollback (see below)
Cmd+clickOpen 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+CSelect 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+BackspaceDelete to start of line / previous word
Cmd+Delete / Option+DeleteDelete to end of line / next word
Cmd+↑ / Cmd+↓Scroll back / forward a line
Cmd or Shift + PageUp / PageDownScroll back / forward a page
Cmd or Shift + Home / EndTop / bottom of scrollback
Option+keySent as Meta (Esc+key); see option_as_alt
Cmd+dragMove 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.

KeyAction
Enter, ↑ or Cmd+GPrevious (older) match
Shift+Enter, ↓ or Cmd+Shift+GNext match
Cmd+VPaste into the query
Option+BackspaceClear the query
EscClose 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: like buttonless, with the traffic-light buttons
  • none: no title bar or border at all, square corners; move the window with Cmd+drag
  • full: the standard title bar (dark when the background is dark)

Finding your way around

FileWhat's in it
src/main.rsWindows, the event loop, keyboard shortcuts, mouse and selection
src/term.rsTerminal state and escape-sequence handling (the xterm subset)
src/input.rsKey and mouse events → bytes for the program
src/renderer.rswgpu setup, glyph atlas, building each frame
src/shader.wgslThe one shader: instanced rects and glyphs
src/font.rsFont lookup, fallback, shaping and rasterizing (swash)
src/boxdraw.rsProcedurally drawn line and block characters
src/pty.rsStarting the shell on a pseudo-terminal
src/config.rsConfig file and defaults
src/notify.rsDesktop notifications and opening links
src/settings.rsThe Settings window's link to the config file, and the AI setup prompt
src/menu.rsleaf's items in the macOS app menu
macos/Settings.swiftThe Settings window (SwiftUI), built by build.rs as leaf-settings
shell/leaf.zshShell 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.