Skip to content

User Guide

A waftty window is its menu bar and its terminal, with a slim tab strip between them once it holds more than one tab. The window title names the tab it shows. Each tab runs your shell and reads and writes its own character encoding.

Shortcuts

Programs in the terminal need Ctrl with a letter, so on Linux and Windows waftty's shortcuts use Ctrl+Shift; on macOS they use Command. F10 opens the menu bar. Edit > Settings > Shortcuts changes any of them.

Command Linux and Windows macOS
Command Palette Ctrl+Shift+P Cmd+Shift+P
New Tab / New Window Ctrl+Shift+T / Ctrl+Shift+N Cmd+T / Cmd+N
Close Tab / Close Window Ctrl+Shift+W / (the window's close button) Cmd+W / Cmd+Shift+W
Quit Ctrl+Shift+Q Cmd+Q
Copy / Paste / Select All Ctrl+Shift+C / Ctrl+Shift+V / Ctrl+Shift+A Cmd+C / Cmd+V / Cmd+A
Settings Ctrl+, Cmd+,
Zoom In / Zoom Out / Reset Zoom Ctrl+= / Ctrl+- / Ctrl+0 Cmd+= / Cmd+- / Cmd+0
Fullscreen F11 Ctrl+Cmd+F
Show Menu Bar Ctrl+Shift+M
Find / Find Next / Find Previous Ctrl+Shift+F / Ctrl+Shift+G / Ctrl+Shift+H Cmd+F / Cmd+G / Cmd+Shift+G
Previous Prompt / Next Prompt Ctrl+Shift+Up / Ctrl+Shift+Down Cmd+Up / Cmd+Down
Select Last Command Output Ctrl+Shift+O Cmd+Shift+O
Copy Mode Ctrl+Shift+X Cmd+Shift+X
Open / Copy a Link by Keyboard Ctrl+Shift+E / Ctrl+Shift+Y Cmd+Shift+E / Cmd+Shift+Y
Save Scrollback Ctrl+Shift+S Cmd+Shift+S
Scroll Up / Down a Page Shift+Page Up / Shift+Page Down the same
Scroll to Top / Bottom Ctrl+Shift+Home / Ctrl+Shift+End Cmd+Home / Cmd+End
Clear Scrollback Ctrl+Shift+K Cmd+K
Reset and Clear (none; the Terminal menu or the palette) Cmd+Option+K
Recent Directories Ctrl+Shift+R Cmd+Shift+R
Recent Sessions Ctrl+Shift+. Cmd+Shift+.
Processes Ctrl+Shift+\ Cmd+Shift+\
Show Status Bar Ctrl+Shift+2 (the key that types @) Cmd+Shift+2
Next Tab / Previous Tab Ctrl+Tab / Ctrl+Shift+Tab (also Ctrl+Page Down / Ctrl+Page Up) the same, or Cmd+Shift+] / Cmd+Shift+[
Tab 1 to 8 / Last Tab Alt+1 to Alt+8 / Alt+9 Cmd+1 to Cmd+8 / Cmd+9
Switch to Last Tab Ctrl+Shift+L Cmd+Shift+L
Move Tab Left / Right Ctrl+Shift+Page Up / Ctrl+Shift+Page Down Cmd+Shift+Page Up / Cmd+Shift+Page Down
Split Right / Split Down Ctrl+Shift+D / Ctrl+Shift+B Cmd+D / Cmd+Shift+D
Next Pane / Previous Pane Ctrl+Shift+] / Ctrl+Shift+[ Cmd+] / Cmd+[
Close Pane Ctrl+Shift+J Cmd+Option+W

A right click on the terminal offers the link entries, Copy, Paste, Select All, New Tab, Split Right, Split Down, Close Pane, Recent Directories, Recent Sessions, Find, Clear Scrollback, Send Signal, Zoom, Command Palette, Show Menu Bar and Settings.

Command Palette

Ctrl+Shift+P (Cmd+Shift+P on macOS) opens the command palette. It lists every command, named with its group, as in "Terminal: Split Right". Typing narrows the list to the commands holding what you type anywhere in their name: "pri" finds New Private Tab and New Private Window. Up and Down move the highlight, Tab completes the search to the highlighted command, and Enter or a click runs it. Esc clears the search, and closes the palette once it is empty.

The palette reaches every command, so the menu bar can stay hidden: View > Show Menu Bar (Ctrl+Shift+M) hides it, and the palette's Show Menu Bar brings it back.

Tabs

  • A tab is named for the command in front and the folder it works in, as claude: ~/dev/waftty while Claude Code runs or bash: ~/dev/waftty at the prompt; the window title shows the same. A command that prints nothing yet shows once it prints or ends. The tab's tooltip adds the title the program set, and --title names a tab whatever runs in it.
  • Drag a tab to reorder it. The Tabs menu and a right click on a tab pin it, close the others, or close the tabs to its right. Pinned tabs sit first and stay open.
  • A tab whose program rings the bell or posts a notification while hidden is marked until you look at it.
  • Drag a tab out of its window, or choose Move Tab to New Window from its menu, to give it a window of its own. Drop a tab on another window of the same waftty, on its tab strip or anywhere on a window showing one tab, to move it there; a split tab moves with its panes, and a window left without tabs closes.
  • Closing a tab, window or waftty while a program runs asks first and names the program. Exit Anyway (or E, or Left then Enter) closes it anyway; Cancel (C or Esc) keeps it. Every dialog's buttons answer the letter underlined in their labels, and the arrow keys move between them.

Recent Directories

waftty remembers the folders its tabs work in, latest first, the last 50 of them. Ctrl+Shift+R (Cmd+Shift+R on macOS) lists them, without the one the tab is in and any that are gone. Type part of a folder's path to narrow the list, Tab completes the search to the highlighted folder, and Enter or a click goes there: at a shell's prompt waftty clears the line and types the cd, and while a command runs it opens a new tab in the folder instead. Private tabs add nothing to the list, and Terminal > Clear Recent Directories (or the palette) forgets every folder on it.

Recent Sessions

When Claude Code, Codex or pi runs in a tab, waftty notes the session it runs: the agent, the session's title or first prompt, the folder it works in, and when it began. A running session is noted each time the agent stops working or asks for something, and again when it exits (or its tab closes), so sessions still running are listed too, from every waftty window and process. waftty reads these from the session records the agents keep themselves (~/.claude, ~/.codex and ~/.pi, or the folders CLAUDE_CONFIG_DIR, CODEX_HOME, PI_CODING_AGENT_DIR and PI_CODING_AGENT_SESSION_DIR name), so nothing is taken from the screen. Ctrl+Shift+. (Cmd+Shift+. on macOS) lists the last 20, latest first, as claude · Version 0.6.1 release · ~/dev/waftty · 11/13/26 1:20PM. Type part of an entry to narrow the list; Enter or a click opens a new tab in the session's folder, types a cd to that folder (a shell's startup file may change folders first) and then claude --resume, codex resume or pi --session with its id, so the shell's own environment applies and its prompt comes back when the agent ends. A session the agent was never given a prompt in has nothing to resume: it is listed as "New session", and choosing it starts the agent afresh in its folder. Private tabs add nothing, and Terminal > Clear Recent Sessions forgets the list. Sessions are noted on Linux, macOS and FreeBSD, where waftty can see which program runs in a tab.

Processes

Ctrl+Shift+\ (Cmd+Shift+\ on macOS), or View > Processes, lists waftty and every process its tabs started, with the tab each belongs to, its CPU use, its memory, and how fast it reads and writes the disk. The list refreshes every two seconds. It opens sorted by CPU, highest first; Settings > Behavior changes that to memory, or to lowest first, and a click on a column sorts by it, a second click the other way. Select a process, pick a signal and press Send Signal to send it (Terminate by default); on Windows End Process ends it. Esc or Close closes the list. FreeBSD shows no disk figures.

View > Show Status Bar (Ctrl+Shift+2, the key that types @; Cmd+Shift+2 on macOS) shows the totals of that list under the terminal: CPU 3.2% · Memory 412 MB · Disk 0 B/s read, 12 KB/s written · 5 subprocesses. It reads the processes every two seconds while it is shown, and not at all while it is hidden or the quick terminal is put away; Status bar refresh under Settings > Appearance sets that from 1 second to 3600 (an hour). CPU and disk figures are averages since the last reading.

Alerts

When a command that ran a while finishes in a tab you are not looking at, waftty marks the tab and posts a desktop notification, such as "make finished", with how long it ran and the tab's name. It does the same when a program asks you something, such as a permission, a question or a sign-in, going by what the program itself says: Codex, Claude Code and other programs report their status to the terminal (OSC 7501, the Program Status Protocol), and Claude Code also records its state. A program ending its turn, finishing, or still running commands it started does not alert. Settings > Behavior turns off each kind of alert apart and sets how many seconds a command must run (10 by default).

Private Tabs and Windows

Private windows and tabs let you work in a temporary directory or run dangerous commands without history pollution. File > New Private Tab and File > New Private Window open tabs whose shell writes nothing to its history file. bash, zsh, fish and PowerShell keep the session's own history, so Up still brings back earlier lines; nushell and xonsh keep none at all. waftty records nothing of a private tab either: its folders stay out of Recent Directories, and it is left out of the windows reopened at the next start. A private tab says "(private)" after its name; every tab and pane a private window opens is private, and so is a pane split off a private tab.

waftty can do this for these shells:

Shell How
bash starts it with a startup file that runs your usual ones, then unsets HISTFILE
zsh starts it with a ZDOTDIR that hands startup back to your own files and unsets HISTFILE before each prompt
fish fish --private
nushell nu --no-history, which also leaves no history to recall in the session
xonsh runs a startup file before yours that turns history off (XONSH_HISTORY_BACKEND = 'dummy') once yours have run
sh dash keeps no history; bash running as sh gets an empty HISTFILE
PowerShell Set-PSReadLineOption -HistorySaveStyle SaveNothing after your profile
cmd keeps its history in memory only

For any other shell waftty says it cannot keep the history private and opens no tab. Programs you run inside the tab, such as a Python prompt or psql, keep their own history as they always do.

Split Panes

  • Terminal > Split Right and Split Down divide the focused pane and start your shell in the new one, in the same folder.
  • Drag the divider between two panes to resize them. A click focuses a pane; Next Pane and Previous Pane move through them in reading order.
  • Close Pane closes the focused pane, and its neighbor takes the space. A pane whose program exits closes the same way.
  • A split tab is one tab in the strip, named for its focused pane. Close Tab closes it with all its panes.

Quick Terminal

waftty --quick                     # or --quick-terminal
waftty --quick-position=left       # hang it from the left edge this time

opens waftty as a quick terminal: a window without a frame that hangs from an edge of the screen above other windows, on whichever virtual desktop you are on. Its shortcut, F12 unless Settings > Quick Terminal names another, shows it with one press and hides it with the next, from any application. It has no menu bar; a right click reaches Settings, Check for Updates, About and Quit. Position on the same page hangs it from the top (the default), bottom, left or right edge, and --quick-position overrides that for one launch. It spans its edge and reaches half way across the display until you resize it by dragging the edge facing the rest of the screen, which a line marks; it then keeps the size you left it at, apart from the size waftty's other windows remember. Length and Depth set that size, in percent of the display along the edge and out from it.

Add waftty --quick to your desktop's startup applications to have it ready at login. Launching it again while it runs shows the running one.

  • On X11, Windows and macOS waftty takes the key itself. If another application, such as another quick or drop-down terminal, already holds it, waftty says so; choose another key on the Quick Terminal page.
  • On Wayland the desktop's GlobalShortcuts portal takes it, and the desktop may ask you to confirm or change the key. Where the desktop has no such portal, bind a desktop shortcut to waftty --quick, which shows the running quick terminal.

Find

Terminal > Find searches the whole scrollback, with options for case, whole words and regular expressions, and shows how many matches it found. The search field offers your earlier searches.

Copy Mode

Terminal > Copy Mode selects and copies text without the mouse, anywhere in the screen and the scrollback. A cursor of its own starts where the program's is, and a frame round the terminal shows the mode is on. While it is, keys go to copy mode, not the program.

Key Does
Arrows, or H J K L Move a cell or a row
W / B Next / previous word
0 or Home / $ or End Start / end of the line
Page Up / Page Down A screen up / down
G / Shift+G The oldest row kept / the program's cursor
V or Space Start or drop a selection
Y, Enter or Ctrl+Shift+C Copy the selection (the cursor's line without one) and leave
Esc or Q Leave

Edit > Open a Link by Keyboard labels every link and file path on the screen with a letter or two; type a label to open that link, as a Ctrl+click would. Copy a Link by Keyboard copies it instead. Esc leaves without choosing, and Backspace takes back a typed key.

Saving Output

File > Save Scrollback writes everything the tab keeps, the oldest row first, to a text file; Save Selection writes what is selected. A long line that wrapped on screen comes back as one line. Open Scrollback in Editor saves the scrollback to a file in the system's temporary folder and opens it in the editor Settings name, or with the desktop's default application.

A saved terminal holds only what the scrollback kept: a full-screen program redraws its screen in place, and the oldest rows leave once the scrollback is full. For a complete record of an agent's work, keep the agent's own log.

Pasting

With Ask before pasting several lines on in Settings, a paste of several lines or of control characters asks first; it is off by default. Pastes of up to 16 MiB reach the program as fast as it reads them, as one paste: typing meanwhile follows the paste, and Esc or Ctrl+C stops it where the program has got to. A paste that can't be sent says why.

Shell Integration

When the shell marks its prompts and its commands' output (OSC 133) and says which folder it is in (OSC 7), waftty knows where each command starts and ends:

  • Previous Prompt / Next Prompt scroll from one prompt to the next.
  • Select Last Command Output selects everything the last command printed.
  • New tabs and windows open in the folder the shell is in.

waftty carries the scripts that do this for bash, zsh, fish, nushell, xonsh and PowerShell; waftty --shell-integration SHELL prints one. Add the line for your shell to its startup file. Each runs only in waftty and leaves your prompt as it is.

# ~/.bashrc
[ "$TERM_PROGRAM" = waftty ] && eval "$(waftty --shell-integration bash)"
# ~/.zshrc
[[ $TERM_PROGRAM == waftty ]] && eval "$(waftty --shell-integration zsh)"
# ~/.config/fish/config.fish
test "$TERM_PROGRAM" = waftty; and waftty --shell-integration fish | source

Nushell writes the marks and the folder itself, and has them on unless your config turns them off. waftty --shell-integration nu prints the two settings; in config.nu:

$env.config.shell_integration.osc133 = true
$env.config.shell_integration.osc7 = true
# ~/.xonshrc
if ${...}.get('TERM_PROGRAM') == 'waftty':
    execx($(waftty --shell-integration xonsh))
# $PROFILE
if ($env:TERM_PROGRAM -eq 'waftty') { waftty --shell-integration powershell | Out-String | Invoke-Expression }

To check it works, run a command, then press Ctrl+Shift+O: the command's output should be selected. Without integration, the prompt commands say that shell integration is off.

Keyboard Protocol

Programs that ask for it (with kitty's keyboard protocol) get keys other terminals can't tell apart, such as Shift+Enter, Ctrl+I apart from Tab, and key releases. Programs that don't ask get the classic xterm keys they always had.

Notifications from Agents

waftty alerts only when a program needs you, going by what the program itself says:

  • Codex and Claude Code report their status to the terminal (OSC 7501, the Program Status Protocol); nothing to set up. A permission prompt or a question in a tab out of view alerts; a finished turn does not.
  • pi: copy waftty-status.ts to ~/.pi/agent/extensions/. Whenever an extension asks you something, such as a permission or a choice, the tab alerts.
  • mini-swe-agent: put waftty_status.py in a folder on PYTHONPATH and run mini --agent-class waftty_status.ReportingAgent. Asking you to confirm its commands alerts.
  • Any program can do the same: report blocked by OSC 7501, ask with iTerm2's OSC 1337 ; RequestAttention=yes, or ring the bell or post a desktop notification (OSC 9, 99 or 777), which mark a hidden tab:

    printf '\033]7501;state=blocked:app=deploy:kind=question\033\\'
    

A program that reports its status alerts through those reports alone, so its bells and notifications do not mark the tab as well. Settings > Behavior turns these alerts off, and long command alerts apart from them; see Alerts.

Starting waftty

waftty --working-directory ~/dev/project     # the first tab starts there
waftty --title review -e codex               # the tab keeps this name
waftty --hold -e ./run-checks                # the tab stays open after it ends

waftty --quick starts the quick terminal. Each launch of waftty is a program of its own; --single-instance opens the window in the waftty already started with --single-instance instead, with its folder, program, title and --hold, so tabs move between all of those windows. Its shells share that waftty's environment variables. Every argument after -e is the program's own. --hold keeps the program's last screen and adds the status it exited with; close the tab when you are done. A folder or a program on the command line starts a new session rather than reopening the last one.

waftty recognizes links that programs mark with OSC 8, plus URLs, email addresses and file paths in the text, including ones a long line wraps across.

  • Ctrl+click (Command+click on macOS) a link to open it. Right click it to open it, copy it, or copy an email address.
  • Ctrl+click a file path (such as src/main.gos:42:7 in a compiler error) to open it in the editor Settings name, at its line and column, or with the desktop's default application.
  • Drop files on the terminal to paste their paths, quoted for the shell.

Character Encodings

Terminal > Set Encoding switches the current tab between UTF-8 and other encodings, grouped by region. The default for new tabs is in Settings.

Signals

Terminal > Send Signal sends a signal to the job in the foreground of the tab: Interrupt, Terminate, Kill and the other common ones by name, the rest under More. Not available on Windows.

Settings

Edit > Settings opens a window with five pages. Each value has a button that puts it back to its default; only values that differ from the defaults are saved, so the defaults follow your desktop.

  • General: the shell, as a command line (empty runs your login shell, as a login shell on macOS; PowerShell on Windows), the starting folder (empty is your home folder), where new tabs open, the character encoding, whether new windows open at their last size or at the columns and rows set there, whether windows and tabs come back at the next start, and whether closing a running program asks first.
  • Appearance: the font, its size and weight (empty uses the desktop's monospace font), ligatures, font features and variations, the fonts and weight of bold and italic text, the color scheme, the cursor shape and blinking, bold text in bright colors, readability adjustment, padding, background opacity (below 100 percent the desktop shows through the terminal, where it blends windows), the scrollbar and its side, the menu bar, the tab bar, and the status bar and how often it refreshes.
  • Behavior: scrollback lines, scrolling on output and typing, the characters a double click selects, copying on select, asking before pasting several lines, the bell (mark the tab, flash or sound), notifications, alerts and how long a command runs before its end alerts, how Processes sorts, programs writing the clipboard (OSC 52; they can never read it), the editor for file paths (such as nvim +{line} {path}), on macOS whether Option is Meta, and on Linux whether keys go through the input method (see below).
  • Quick Terminal: the shortcut that shows and hides the quick terminal, the edge it hangs from, and its length and depth.
  • Shortcuts: every command's chords.

Font features and styles

Font features turns a font's OpenType features on or off, separated by spaces or commas: ss01 or +ss01 turns a stylistic set on, -calt turns contextual alternates off, and cv01=2 picks the second form of a character variant. A coding font such as MonoLisa or Fira Code lists its features on its site.

Font variations sets a variable font's axes by their tags, such as wdth=90 slnt=-5; the weight comes from the font weight setting.

Bold text draws in the font's bold, 300 heavier than the font's weight, and italic text in the font's own italic, or in its upright letters slanted where it has none. Bold font, Bold weight, Italic font and Bold italic font give each style a font or weight of its own.

Settings are saved in the configuration directory:

Platform Configuration directory
Linux $XDG_CONFIG_HOME/dev.gossamer.waftty (default ~/.config/dev.gossamer.waftty)
macOS ~/Library/Application Support/dev.gossamer.waftty
Windows %APPDATA%\dev.gossamer.waftty

In portable mode the configuration directory is user/dev.gossamer.waftty beside waftty instead.

Dialog text and controls follow the desktop's interface font size.

Input Method

On Linux, an input method such as ibus or fcitx composes Chinese, Japanese and Korean text, and every key waits for it, about a millisecond. Use the input method decides whether waftty sends keys through it:

  • When it has more than keyboard layouts (the default): waftty asks ibus (its preloaded engines) or fcitx5 (its profile) which engines are set up, and uses the input method only when one of them is more than a keyboard layout.
  • Always or Never.

The choice applies at the next start. Programs in the tabs keep the desktop's input method either way.

Color Schemes

The built-in schemes are System theme (light or dark with the desktop), Light, Dark, Solarized Light, Solarized Dark, High Contrast Light and High Contrast Dark.

  • Edit Colors opens the current scheme's colors; OK saves them as a scheme by the name you give it.
  • Import Scheme reads iTerm2 (.itermcolors), Windows Terminal (.json), xfce4-terminal (.theme) and base16 (.yaml) schemes.
  • Open Schemes Folder shows the folder scheme files live in.

A scheme file is scheme-NAME.toml in the configuration directory:

name = "Night Sky"
appearance = "dark"          # "light" or "dark": the window around the terminal
foreground = "#d8e7f2"
background = "#0c1824"
cursor = "#74c6f4"
selection = "#1f4d70"
selection_text = "#ffffff"
ansi = [
  "#0c1824", "#e06c75", "#98c379", "#e5c07b", "#4bb7ee", "#c678dd", "#56b6c2", "#d8e7f2",
  "#3b5368", "#ff7b86", "#b5e890", "#ffd88a", "#86cff5", "#de9bf0", "#7fd8e2", "#ffffff",
]

Updates

Help > Check for Updates asks GitHub for the latest release. When it is newer than the waftty running, Download opens its page; otherwise waftty says it is up to date. waftty checks only when asked.

Custom Shortcuts

The Shortcuts page of Settings writes shortcuts.toml in the configuration directory, which maps a command id to a chord or a list of chords; an empty list removes a command's shortcut. waftty refuses chords the terminal needs, such as a bare letter, Ctrl with a letter, or Alt with a letter, and says which entries it could not use.

"tabs.next" = ["Ctrl+Tab", "Ctrl+Shift+Right"]
"view.fullscreen" = []

Every command can be rebound, including Undo, Redo and Cut in waftty's text fields and the toolkit's Toggle Inspector. The Send Signal and Set Encoding entries (terminal.signal:15, terminal.encoding:KOI8-R) can only be bound in the file. A command bound to Ctrl+Shift+C, Ctrl+Shift+V, Shift+PageUp or Shift+PageDown takes the chord from the terminal's own copy, paste and scrolling.