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, bash or fish it turns on command blocks automatically, without touching your dotfiles.

Configuration

There's nothing to configure. On macOS, litty → Settings… (⌘,) changes the common settings with native controls. On Linux, Ctrl+Shift+, (or Settings… in the right-click menu) opens the config file in your editor. The file is ~/.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
font = JetBrains Mono # family name or path to a .ttf/.otf
padding = 10          # points
scrollback = 20000
background = #1a1b26  # and foreground, selection, cursor-color, color0 … color15
keybind = ctrl+shift+k = split-right
restore = true
quick-terminal = ctrl+`
term = xterm-256color
paste-warning = true
background-opacity = 1.0
background-blur = false

Changes apply as soon as litty's window is back in front: a new theme also recolours what's already on screen and in the scrollback. quick-terminal applies 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.

Right-click for Copy, Paste, Open Link, Split Right / Down, Clear, Reopen Closed Tab and Settings (a native menu on macOS). Drop files on the window to type their paths, escaped for the shell. Pasting several lines into a shell without bracketed paste shows paste 3 lines? Enter: paste · Esc: cancel, so a copied command never runs by accident.

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.

Closed a tab by mistake? ⌘⇧T (Reopen Closed Tab in the right-click menu on Linux, where Ctrl+Shift+T is New Tab) brings it back with its splits, each pane in its folder. litty remembers the last 10 closed tabs until it quits.

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.

Sessions & quick terminal

Quit litty with ⌘Q (Ctrl+Shift+Q on Linux, or Quit in the hamster's menu) and the next launch reopens your windows, tabs and splits, each pane in the folder it was in. Programs that were running aren't restarted. Closing the windows yourself starts fresh next time, and restore = false turns this off.

On macOS, quick-terminal = ctrl+` (any keys you like) makes a system-wide shortcut that drops a terminal across the top of the screen from whatever app you're in, and hides it again. It uses the standard hot-key API, so litty doesn't need accessibility permissions, and nothing is loaded unless you set it.

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, bash and fish this works out of the box: litty loads a tiny hook for that session only and never edits your dotfiles (bash 4.4 or newer also reports command names). 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.8.4-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.

You can also click the notice (handy on Ubuntu, where the input method uses Ctrl+Shift+U for Unicode). If litty came from the .deb or .rpm, Enter downloads the signed package and installs it right away; the system asks for your password and the next launch runs the new version.

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

If Homebrew, Nix or cargo installed litty, 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, or uses the font from your config. Either way:

• Nerd Font icons always work: the symbols are built in, and read only when an icon is on screen. Powerline arrows are drawn to fill the cell so prompt segments join.
• Characters no loaded font has (Chinese, Japanese, Korean, Indic scripts …) are found through fontconfig.
• Thai, colour emoji (including flags, skin tones and families) and box drawing work.

Images

litty shows pictures by itself, no other tools needed:

PNG and JPEG work. Big pictures are shrunk to fit the window before they're sent, and photos are turned upright using their EXIF orientation. It works over ssh when the other machine has litty installed. GIF, WebP and animation aren't supported.

Installed litty from the .dmg? The litty command isn't on your PATH yet (Homebrew adds it for you). Add it once with sudo mkdir -p /usr/local/bin && sudo ln -sf /Applications/litty.app/Contents/MacOS/litty /usr/local/bin/litty.

litty also speaks the Kitty graphics protocol, which is what litty img uses, so other tools that use it show real pictures too:

PNG, RGB and RGBA work, sent directly, from a file or through a temporary file. An image scrolls with the text it was printed with and is freed when that text leaves the scrollback; each pane keeps at most 64 MB of images, dropping the oldest first. Sixel and images inside tmux aren't supported yet.

Compatibility

litty sets TERM=xterm-256color, COLORTERM=truecolor and TERM_PROGRAM=litty. With term = xterm-litty programs also learn about undercurl, underline colours and synchronized output from litty's own terminfo entry, which comes with the app and the packages. Hosts you ssh into need it too: infocmp -x xterm-litty | ssh host tic -x -.

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
litty img a.jpg  # show pictures in the current terminal (PNG, JPEG)

Troubleshooting