Skip to content

The terminal ​

Escape sequences behave as they do in Ghostty.

TERM ​

TERM is xterm-ghostty, which comes with insensical:

  • If your system has it, that one is used. Otherwise the daemon compiles its own with your system's tic the first time a pane starts.
  • With no tic, TERM is xterm-256color.
  • term = "xterm-256color" in the settings makes it that for every pane started afterwards.

Over ssh to a machine without that description, programs complain about an unknown terminal. Install it there (infocmp -x xterm-ghostty | ssh host tic -x -), set TERM=xterm-256color for that command, or set term if most of your work is on other machines.

Every pane also has COLORTERM=truecolor, TERM_PROGRAM=insensical, TERM_PROGRAM_VERSION, INSENSICAL_PANE and INSENSICAL_SOCKET.

On a Mac, a pane gets LANG when insensical has none of LANG, LC_ALL and LC_CTYPE, as it doesn't when you open it from the Dock or Finder. It's your language and region from System Settings in UTF-8, such as en_US.UTF-8, or en_US.UTF-8 if your Mac has no locale for them. Without it, programs treat every letter outside ASCII as bytes. A LANG you set yourself is kept.

Scrollback ​

Each pane keeps 10 MB of history. The scrollback setting changes it, from 1 to 200 megabytes, for panes started afterwards. The daemon holds the history; Stopping, restarting and new versions covers what happens to it when the daemon stops.

  • The window shows what each project's programs hold. The sidebar shows the memory and processor share of everything running in a project, beside its heading: 1.2 GB · 40% cpu. The overview shows it per pane, and isc usage prints it.

History from another machine comes a part at a time. With --host, a pane shows its screen and the newest half megabyte at once. Scroll to the top and the next four megabytes are fetched, and so on. The top of the scrollbar's track is marked while there's more to come, and searching looks only through what has come.

From command to command. Ctrl+Shift+Up scrolls to the prompt of the command before what you're looking at, and Ctrl+Shift+Down to the one after (⌘↑ and ⌘↓ on macOS).

  • It needs a shell that marks its prompts: fish 4 does, and bash and zsh do with the line isc shell-integration prints. Without marks the keys do nothing.
  • After the last command, Ctrl+Shift+Down goes to the bottom.

Clearing it. Ctrl+Shift+L (⌘K on a Mac, leader C) empties the pane's history and its screen, in every window and browser that shows it. The program then draws again: a shell its prompt, a full-screen program its screen. Nothing is typed into it. What the pane keeps for after a restart is emptied too.

  • The eraser button in a pane's header does the same. One on a tab, and on a project's heading in the sidebar, clears every pane in it. Each is also in the palette.

  • A pane is busy when something other than its shell runs there, or it says it's running. A busy pane isn't cleared until you say so: you're told what runs there and asked. A tab or a project always asks first, and names its busy panes.

  • isc clear does the same from any terminal. It clears the pane you run it in, or the one with the keyboard. Name another by number or name.

  • --tab clears every pane of this pane's tab, or of the tab you name. --project does the same for a project.

  • With busy panes, isc clear clears nothing, names them and exits with an error. --force clears them anyway.

Text ​

  • Font. font-family names the terminal's font. font-size is in points: 12 by default, 13 on macOS. On Linux a point is 1⅓ pixels. The text around the terminals has its own font: see Appearance.
  • There's no font weight setting.
  • Ligatures. Symbols side by side are drawn as the font's ligature, if it has one: ->, !=, <=, ===. font-ligatures = false turns that off. Letter ligatures such as www or fi aren't formed, nor are symbols a program gave different colours or weights.
  • Characters the font lacks, emoji included, come from the system's fallback fonts. A wide Nerd Font glyph can overlap its neighbour.
  • Cursor: block, bar or underline as the program asks, in the theme's cursor colour or the program's.
    • It blinks until a program asks for a steady one.
    • Only the pane you type in has a solid cursor. Other panes show an outline, as does every pane while the window isn't in front or a panel has the keyboard.
  • Half-drawn screens are held. When a program says it's mid-draw (synchronized output), its screen shows when it says it's done, or after one second.

Colours ​

  • The sixteen named colours come from the theme. 256 colours and true colour show as the program gives them.
  • On a light theme, text that programs drew for a dark terminal, such as pale yellow or white, is painted in a darker colour from the theme's own, so you can read it against its background (4.5:1). Text on a coloured cell is measured against that cell. What you copy is unchanged.

Selecting and copying ​

  • Drag to select. Click twice to select the word, three times for the line. Hold Alt while you drag to select a rectangle. Hold the pointer beyond the top or bottom to scroll.
  • Selecting copies to the selection clipboard on systems that have one (Linux).
  • Press Ctrl+Shift+C to copy to the clipboard. The selection turns the accent colour for a second and "Copied" (or "Copied 14 lines") shows at the bottom of the pane. With nothing selected, nothing is copied. Wrapped lines are joined.
  • select-all selects everything in the pane. It has no default key.
  • Typing returns to the bottom and clears the selection. A selection stays on its text as output arrives.

Selecting with the keyboard ​

Move through a pane's screen and history, select and copy, without the mouse. Start with Ctrl+Shift+X (⇧⌘X on a Mac), the leader then v, or "Select and copy with the keyboard" in the palette. The same key leaves.

  • While it's on, every key is its own. Nothing you press reaches the program.
  • It starts at the program's cursor, usually the line you're looking at. A strip at the foot of the pane shows the keys that work right now.
  • Copying leaves. y or Enter copies and ends it.
  • Escape lets go first, then leaves. With something selected it drops the selection; with nothing selected it leaves. q always leaves. Pasting also leaves.

Moving

KeysWhere the cursor goes
h j k l, or the arrowsLeft, down, up, right
w b eThe next word, the word before, the end of the word
W B EThe same, counting everything between blanks as one word
0 ^ $, Home EndThe start of the line, its first character, its end
g GThe top of the history, and the end
H M LThe top, middle and foot of what's shown
{ }The blank line before, and after
PageUp PageDown, Ctrl+B Ctrl+FA screen up or down
Ctrl+U Ctrl+DHalf a screen
f t, then a characterTo that character on the line, or just short of it
F T, then a characterThe same, going back
; ,To that character again, and the other way
[ ]The command before, and the command after
A number firstDoes the next key that many times: 5j
  • A wrapped line is one line. The wheel and scrollbar still scroll, and a click puts the cursor there.

Selecting

KeyWhat it selects
vFrom here, as you move. Press it again to stop
VWhole lines
Ctrl+VA block
oWith something selected: jumps to the other end of it
oWith nothing selected: the whole output of the command you're in. At a prompt, the output of the command before
cThe command line: what was typed at the prompt you're in or under
pThe path or web address under the cursor, or the nearest on the line
y, EnterCopies and leaves. With nothing selected, copies the line
  • o, c, [ and ] need a shell that marks its prompts (OSC 133). The shells insensical sets up do.

Labels

Press Space and every path, web address, commit and machine address in view gets a letter. Type the letter to copy that one and return to your prompt.

  • The newest get the keys under your fingers: a, s, d, f. With more than 26 in view, labels are two letters.
  • Hold Shift with the letter to select without copying, so you can stretch the selection before y.
  • Escape, or any key that isn't a label, puts the labels away.

Searching

  • / opens the pane's search, starting from the nearest match above the cursor.
  • Enter puts the cursor on the match and returns to selecting. A selection you'd started now reaches the match.
  • Escape closes the search and restores everything. Up and Down step through matches while the field is open.
  • n goes to the match before, N to the one after.

Limits

  • In a full-screen program it works on what's shown, with no history.
  • If the program takes over the screen or gives it back while you select, the selection is dropped and the cursor starts again at the program's.
  • In the window, pressing the leader twice sends the leader's key to the program and leaves.
  • When the link to another machine is lost, it ends. The pane keeps its last picture, dimmed.
  • There's no isc command for it.

Pasting ​

  • Ctrl+Shift+V pastes the clipboard. Shift+Insert or the middle button pastes what you last selected.
  • A paste that would do more than it looks like is held, and you're asked first. That's:
    • more than one line, into a program that hasn't asked for pastes to be marked (bracketed paste), which would run each line as it arrives;
    • text containing the sequence that ends a marked paste;
    • more than one line, into a pane on a machine you marked careful, whatever the program asked for. See Other machines in the window.
  • What a program put on the clipboard (see The clipboard and programs) is pasted like your own copy: a command an agent copied lands at your prompt, where you read it before pressing Enter.
  • The question shows what you'd paste. A card at the bottom of the pane gives the line count, the reason and the text. Control characters show as their sign (␛ for Escape), and invisible or direction-changing ones by number, as in <U+202E>.
  • Press Enter or click "Paste" to paste. Press Escape or click "Cancel" to drop it.

Mouse and wheel ​

  • A program that asks for the mouse gets presses, releases, motion and the wheel. Hold Shift to select text instead.
  • The wheel scrolls history, three rows per notch. In a full-screen program it sends arrow keys, or goes to the program if it asked for the mouse.
  • A scrollbar shows while the view is scrolled back, and when the pointer is at the pane's right edge. Drag its thumb.

Finding text ​

Press Ctrl+Shift+F to open a field over the pane's top right corner.

  • It finds text anywhere in the history, ignoring case, shows which match you're on and how many there are, and brings each match to the middle, selected, so you can copy it.
  • Enter goes to the previous (older) match, Shift+Enter to the next. Escape returns to where the program is writing.
  • Text is found across a wrap over two rows, not three. There are no regular expressions.

Web addresses and paths ​

  • Ctrl+click a web address to open it (⌘-click on macOS).
  • Ctrl+click a file's path to open it or show it in your file manager, by the kind of file (see "What a click on a path does" below).
  • A web address is underlined under the pointer, and a note in the pane's bottom right shows where it leads, as in "Ctrl+click opens localhost:5173".
  • A path is marked only while you hold Ctrl, and the note says what the click will do: "Ctrl+click opens main.rs in src/".
  • Only http:// and https:// addresses are opened.
  • A path is marked only if it exists. It's read from the pane's directory, and ~/ is the home directory. A line and column, as in src/main.rs:12:5, go to the editor you chose with open-files-with; your desktop's opener opens the file at its beginning. Paths on network or automounted file systems aren't looked up.
  • Links a program marks (OSC 8), such as an agent's "open the pull request" or the file names of ls --hyperlink, work the same way. Only a web address, or a file:// link to a file that exists on this machine, is followed.
  • The note names the machine first. Names with letters outside ASCII are shown in their network form (xn--mnchen-3ya.example), and a name and password before the machine aren't shown.
  • A click follows only what the note said. If the words changed under the pointer, the click opens nothing and the note shows the new destination. Click again to follow.
  • An address or path with an invisible or direction-changing character is never marked or opened.

What a click on a path does. A path opens only when opening it just shows it.

  • With open-files-with at system, plain text, source code, pictures and PDFs open in your desktop's usual program. csv and tsv don't, because a spreadsheet works out formulas.
  • Everything else is shown in your file manager: directories, programs, scripts, web pages, installers and files with no ending.
  • So is a file someone else could replace, such as one in /tmp or in a directory your group can write to, and a file whose content doesn't look like its name.
  • With an editor chosen in open-files-with, any file opens in it. A directory is still shown in the file manager.
  • A path in a pane on another machine is that machine's. With nvim, vim, hx or nano chosen, Ctrl+click opens it in that editor in a new pane on that machine; otherwise the click copies the path. A web address opens in your browser from any pane.

Choosing the editor. open-files-with says what a Ctrl+clicked file opens in:

ValueOpens the file
system (the default)With whatever your desktop uses for that kind of file, at its beginning, if it's one of the kinds listed above
code, cursor, zed, subl, ideaIn that editor, at the line and column written after the path
nvim, vim, hx, nanoIn that editor in a new pane, split to the right of the one you clicked in, at that line
a command with {file} in itBy running it, with {file}, {line} and {column} filled in: "myedit --goto {line} {file}"
  • With no line after the path, the line is 1.
  • A command of your own is cut into words at spaces and run directly, not by a shell. If it can't start, the file is handled as with system.

The clipboard and programs ​

A program can put text on the clipboard (OSC 52). That's how an editor on another machine, reached over ssh, copies: "+y in Neovim there lands on the clipboard here.

  • Only the program in the pane you're looking at can do this: the pane with the keyboard, in a window that's in front. A program in another tab or a minimized pane is ignored.
  • Pasting it is like pasting anything else. Pasting says when a paste is held.
  • Text only, up to a megabyte, and only the clipboard: requests for the primary selection (OSC 52 with p or s) change nothing.
  • No program can read the clipboard, and no setting allows it.
  • Bursts are limited: at most three texts at once, then one a second. The rest are dropped.
  • clipboard = "never" turns it off. Set on this computer, it holds for every machine's panes.

Pictures ​

Programs can show pictures in a pane: a plot, a thumbnail, a file manager's preview. insensical draws pictures sent by the Kitty graphics protocol, which kitty +kitten icat, chafa, timg, viu, matplotlib's kitty backend and many others use.

  • A picture scrolls with the text, goes into the history, and is cut off at the pane's edge. One too large for its pane is shrunk to fit, in its own shape.
  • Unicode placeholders work, so programs such as Yazi can show pictures. The browser page doesn't draw pictures. The interface in a terminal shows them where your terminal can: see The whole interface in a terminal.

Limits:

  • Sixel pictures aren't shown.
  • A picture must be sent in the escape sequences themselves, not named by a file or shared memory. icat falls back to sending it.
  • Each pane keeps 64 MB of pictures; the oldest off-screen ones are forgotten first.
  • isc capture and copying give the text only.

What the terminal does not do ​

  • Input methods (IME) are off unless you turn them on. With input-method = true, your system's input method (fcitx, ibus, the Mac's) composes text in a pane, shown underlined at the cursor. Turn it off again if typing misbehaves.
  • Sixel images aren't shown; Kitty graphics are (see Pictures).
  • The words of a command running longer than a few seconds are read from the system, so everyone who may see your panes can see them: don't put a secret on a command line.
  • Narrowing a pane rewraps its lines. A full-screen program's screen is cut off at the new edge, and the program draws it again.