litty docs

Getting started

On macOS the quickest way is Homebrew:

On Linux use Homebrew too, or a package from the install section:

Or the install script, which works on both and picks the right file:

litty opens your login shell in your home directory. With zsh it turns on command blocks automatically, without touching your dotfiles.

Configuration

There's nothing to configure. To change a default, create ~/.config/litty/config (or $XDG_CONFIG_HOME/litty/config) with one key = value per line; # starts a comment.

# ~/.config/litty/config
theme = dark          # dark | light | auto
font-size = 14        # points
cursor = block        # block | bar | underline
cursor-blink = false
tray = true           # macOS menu-bar hamster

Changes apply the next time litty starts. Unknown keys are ignored, so an old config never breaks a new version.

Keyboard shortcuts

The Linux column shows the Linux key where it differs; a dash means the shortcut is documented for macOS only.

Mouse. Double-click selects a word, triple-click a line. Hold ⌘ (Ctrl on Linux) and click a URL to open it. Programs that use the mouse (vim, tmux, htop) receive it; hold Shift to select text instead.

Tabs, splits & windows

⌘T opens a tab in the current directory. On macOS tabs are real system window tabs: drag one out to make it a window, and they show up in Mission Control like any other app. On Linux litty draws its own tab bar.

⌘D splits right and ⌘⇧D splits down. Drag a divider to resize, or use ⌘⌃ + arrows; ⌘⌃= makes all splits equal. Inactive panes are dimmed. ⌘⇧↩ zooms the focused pane to fill the tab, and again to go back.

Resizing re-wraps long lines (your prompt stays intact) and keeps the cursor on its text. litty remembers the window size and zoom for next time.

Command blocks

litty knows where each command starts and ends, so it can:

• tint the output of a failed command a faint red,
• show exit 1 2.4s at the end of the line for commands that fail or take half a second or longer,
• jump between prompts with ⌘↑ / ⌘↓,
• mark failed commands on the scroll rail on the right edge,
• copy just the last command's output with ⌘⇧C (no prompt, no command line),
• select a command's whole output by ⌘-clicking its prompt line,
• tell you when a slow command finishes in the background (see below).

Done notifications

When a command that ran 8 seconds or longer finishes while no litty window is in front, the Dock icon bounces, the menu-bar hamster cheers or looks dizzy for ten seconds, and a notification says what finished: cargo build — Done in 2m13s or Failed (exit 101) after 45s. Click it to jump back to that tab. The first time, macOS asks whether litty may send notifications. On Linux the notification goes through notify-send when it's installed.

With zsh this works out of the box: litty loads a tiny hook for that session only and never edits your .zshrc. Other shells work when they emit OSC 133 prompt marks (A at the prompt, C when a command starts, D;status when it ends); many prompt frameworks can do this.

Menu-bar hamster

On macOS, Litty lives in the menu bar:

• Sitting still: nothing is running.
• Running in its wheel: a command has been running for more than a second in some tab.
• Cheering or dizzy: a slow command just finished in the background, successfully or not.
• Stuffing its cheeks: litty is checking for or downloading an update.
• Blue dot: an update is ready.

Its menu shows the update status and can check for updates, install one, open a new window or quit.

It only animates when no litty window is in front (if you can see the terminal, you don't need the hamster), so it costs no CPU while you work. Turn it off with tray = false.

Updates

When litty starts it asks GitHub whether there's a newer release, at most once an hour. If there is, a small ↑ 0.6.0-style notice appears in the corner of the window.

1. Press ⌘⇧U (Ctrl+Shift+U on Linux) to open it.
2. Enter downloads the release in the background; it's installed when you quit litty. Esc skips that version.

Every download is checked against an ed25519 signature before anything is replaced, so a tampered file is refused.

If a package manager installed litty (Homebrew, apt, Nix, cargo), litty leaves updating to it: the notice shows the command to run, and Enter copies it.

To turn update checks off, start litty with LITTY_NO_UPDATE_CHECK=1.

Fonts

litty uses Maple Mono NF when it's installed: rounded, with ligatures (=> != -> <= |>), Nerd Font icons and powerline glyphs. Put these files in ~/Library/Fonts, ~/.local/share/fonts or ~/.fonts:

MapleMono-NF-Regular.ttf
MapleMono-NF-Bold.ttf
MapleMono-NF-Italic.ttf
MapleMono-NF-BoldItalic.ttf

Without them litty falls back to Menlo on macOS and DejaVu Sans Mono on Linux. Thai, colour emoji and box-drawing characters work either way.

Compatibility

litty sets TERM=xterm-256color and COLORTERM=truecolor.

Thai text

Thai vowels and tone marks stack on their letter the way they should. Because Thai is written without spaces, other terminals select a whole line when you double-click Thai text; litty selects one word: สวัสดีครับ → สวัสดี | ครับ.

It uses a 60,000-word dictionary (PyThaiNLP, public domain) with maximal matching. The dictionary is loaded the first time you double-click Thai text, so startup and memory don't change if you never do.

Recording

Press ⌘⇧R (Ctrl+Shift+R on Linux) to record the focused pane; ● rec shows in the corner. Press it again to stop, and the recording is saved on your Desktop as litty-<date>-<time>.cast.

It's an asciinema file: play it with asciinema play, upload it, or embed it on a web page. Handy for bug reports and demos. Recordings contain everything shown in the pane, so check them before sharing.

Command line

litty            # your login shell
litty -e htop    # run a command instead of a shell

Troubleshooting