Skip to content
jOtterjOtter

Terminal setup

jOtter runs in any terminal. Two terminal features make it much nicer, and not every terminal has them:

  • Graphics. Plots and equations render as real images in terminals that support an image protocol. Everywhere else they are drawn with Unicode half-block characters: recognisable, but blocky.
  • The kitty keyboard protocol. Most terminals send the same bytes for Enter, Shift+Enter and Ctrl+Enter. With this protocol jOtter can tell them apart, so Shift+Enter runs a cell like in JupyterLab.

jOtter detects both when it starts and needs no configuration. See the terminal compatibility table for details on each terminal.

Section titled “Recommended: kitty”

kitty supports both, which makes it the best-supported terminal. Images are sharp, scrolling doesn’t flicker, and every key combination is distinct.

Other terminals

Section titled “Other terminals”

Images: jOtter uses the best protocol your terminal offers: kitty graphics, then sixel, then the iTerm2 protocol, then half-blocks. Ghostty uses kitty graphics, foot uses sixel and WezTerm the iTerm2 protocol; all of them show sharp images. Alacritty has no image protocol.

Keys: kitty, Ghostty, foot and Alacritty speak the kitty keyboard protocol. WezTerm does with enable_kitty_keyboard = true in its config. Without it, use these instead:

Instead of Use
Shift+Enter (run and advance) r in notebook mode
Ctrl+Enter (run in place) Space in notebook mode

Both work in every terminal. To run a cell you are editing, press Esc first.

tmux

Section titled “tmux”

Inside tmux, images need passthrough enabled. Add this to ~/.tmux.conf and restart tmux:

Terminal window
set -g allow-passthrough on

tmux doesn’t forward the kitty keyboard protocol, so use r and Space to run cells there. Ctrl+\ (split a cell) may reach jOtter as Ctrl+4; jOtter treats both the same.

Colours and fonts

Section titled “Colours and fonts”

jOtter uses the terminal’s colours for its interface and a syntax theme for code. The default theme is dark; on a light terminal background, set theme = "base16-ocean.light" in your config.

Images are sized in terminal cells, so they follow your font size. If you zoom the terminal, jOtter re-renders every cell for the new size.