The terminal

Every terminal pane runs your real login shell and uses one of two native, GPU-accelerated terminal backends. Zshell owns the surrounding behavior—pane focus, search, notifications, links, history, themes, and paste safety—so it is consistent whichever emulator you choose.

Terminal backendsCopy link

Choose a backend under Settings → Terminal → Backend:

Both support GPU acceleration, image rendering, Zshell's shared theme catalog, find, mouse reporting, notifications, and progress reports. A backend change applies to new terminals only—existing panes keep the emulator they started with.

Your shell, unchangedCopy link

Each session starts your account's login shell, so your prompt, aliases, functions, and dotfiles load as they do in any terminal. Zshell adds capability and identity variables:

Both backends advertise Ghostty through TERM_PROGRAM because image-aware and notification-aware CLIs use it as a capability hint. Use ZSHELL_TERM only when you genuinely need to distinguish the renderer.

When launched from the Dock or Finder, Zshell reads SSH_AUTH_SOCK from your interactive login shell so SSH connections use the agent selected by your dotfiles. A launch from a terminal keeps its valid inherited agent.

System permissionsCopy link

Local programs in a Zshell terminal can request camera or microphone access, or control of another app through Apple Events. macOS attributes these requests to Zshell; allow access only for programs you trust. Automation approval is specific to each target app.

Manage access in System Settings → Privacy & Security → Camera, Microphone, or Automation. Denying a request blocks that capability. Zshell does not grant these permissions automatically.

Focus follows mouseCopy link

Enable Settings → Terminal → Behavior → Focus follows mouse to focus a terminal when the pointer enters it. It is off by default and works with both backends, including Quick Terminal. It does not take focus during a drag, from an editor, or while a menu or dialog is open.

terminal.focus-follows-mouse = true

SearchCopy link

Find acts on the focused terminal or editor pane and remains active while its search field owns keyboard focus.

Prompt editingCopy link

Click within the active shell prompt to move its input cursor, then keep typing at that position. In a zsh prompt, drag across the input to select a range: typing replaces the selection, while Backspace or Delete removes it. Double- or triple-clicking still select terminal text; programs that enable terminal mouse reporting, such as full-screen TUIs, keep receiving their own mouse events.

If a nested or replacement shell has not loaded Zshell’s prompt editing support, dragging still selects terminal text for copying but does not edit the input. Input selection editing resumes when you exit back to the original prompt.

Claude Code's standard input box supports click-to-position and drag-to-edit on both backends, including wrapped and multi-line drafts. Type or paste to replace the selected input, or press Backspace or Delete to remove it. Vim normal/visual mode, dialogs, attachment or collapsed-paste placeholders, and scrolled transcript text keep their existing terminal selection behavior. Applications that capture the mouse continue to handle their own input.

Voice input from Zisla uses the terminal's paste action. In Claude Code, it also replaces a selected input range; repeating a phrase intentionally remains supported.

Foreground application shortcutsCopy link

When a terminal application's shortcuts conflict with Zshell, right-click its pane and enable Block Zshell Commands. Modified keys, including Ctrl+Return, go to the foreground application while that pane has keyboard focus. Copy, paste, and select all remain available.

The setting applies only to that pane. Right-click again and clear the checkmark to restore Zshell shortcuts. If an application captures the mouse, hold Shift while right-clicking to open Zshell's menu.

Prompt queueCopy link

Focus a terminal and press Cmd+Shift+M, or choose Toggle Prompt Queue in the command palette. The bar opens below that terminal. Type an entry and press Return or Add to Queue; each entry is a single line, with pasted line breaks replaced by spaces.

When the original zsh returns to an empty shell prompt, Zshell sends the next entry and presses Return. Entries run in queue order. Automatic sending waits while an agent or another foreground program owns the terminal, or while the shell prompt contains draft input. It requires Zshell's zsh integration; other shells and nested shells can use manual sending.

Each entry has Send Now and Remove buttons. Send Now immediately sends the text and Return to the terminal's current program, without waiting for a shell prompt. Esc or the close button hides the bar and keeps the queued entries. Each terminal has its own queue; closing that session or quitting Zshell discards it.

Paths and URLsCopy link

Zshell recognizes web URLs and existing local paths printed by terminal programs. Local links can be absolute, ~/-relative, ./ or ../ relative, or relative to the pane's live working directory. A diagnostic suffix such as :42 or :42:7 does not stop the underlying file from being found.

• Command-click a local path to reveal it in Finder, or a URL to open it in the default browser.
• Command-right-click a path for New File Tab / New File Pane, or a URL for New Browser Tab / New Browser Pane.
• Full-screen programs that enable mouse reporting receive an unmodified right-click. Hold Shift while right-clicking to open Zshell's terminal and pane menu instead.

This gives compiler output and agent transcripts a direct route back into the same project. Browser behavior is covered in Browser panes.

NotificationsCopy link

Zshell forwards two terminal events to Notification Center:

• a bell from a session that is not focused;
• an OSC 777;notify request from a program such as a long-running build or coding agent.

Notifications can play the system sound. Clicking one activates Zshell and jumps to the exact session that emitted it. macOS asks for permission only when a terminal first tries to notify you, not when Zshell launches.

Command completionCopy link

Open Settings → Terminal → Command Notifications to have Zshell notify you when a command finishes:

• Long-running commands: choose 5, 10, 30, or 60 seconds. A command that runs at least that long triggers a completion notification. The default is Off.
• Failed commands: notify on a nonzero exit status, regardless of runtime. This is on by default for new configurations and can be disabled independently.

These settings apply to zsh terminals created after the change, on either terminal backend. They use the original shell's command completion event; commands run inside a nested shell or an interactive program do not report individual completions through this integration.

The same settings can be saved in ~/.config/zshell/config.toml:

terminal.notify-finish-seconds = 30
terminal.notify-on-error = true

Set terminal.notify-finish-seconds to 0 to turn off runtime-based notifications. Notification delivery follows your macOS notification settings.

Progress reportsCopy link

Programs that emit OSC 9;4 progress get a slim bar above the terminal, with distinct normal, paused, and error states. There is nothing to enable: if the program reports progress, the pane shows it.

Clipboard, drops, and paste safetyCopy link

• Clipboard reads are confirmed. OSC 52 can ask for the macOS clipboard, including from a remote host over SSH. Zshell asks before returning it.
• Risky pastes are flagged. Multi-line or command-like text is held behind a confirmation instead of being submitted immediately.
• Files and screenshots become shell-safe paths. Finder files are inserted as quoted absolute paths. A clipboard containing only an image is saved as a private temporary PNG, then its path is pasted for the terminal program to read. Remote panes upload copied files and screenshots to their host before inserting remote paths.

Option-key inputCopy link

By default, Option stays with the active macOS input source so layouts such as Polish Pro can type composed characters. Enable Use Option as Alt/Meta in Settings when a terminal program should receive Option-key chords as Meta shortcuts instead. See terminal.macos-option-as-alt.

The zshell commandCopy link

Every Zshell terminal includes a project-aware CLI:

zshell                         # create a project at the current directory
zshell vim ~/src/app.swift     # create it and run this argv in the first terminal
zshell +themes                 # browse and preview themes interactively
zshell +themes --list --dark   # print theme names without the browser
zshell +help                   # show all command groups

The theme browser previews each selection across the whole app; Return saves it and Escape restores the previous theme.

FontsCopy link

Zshell bundles JetBrains Mono plus Nerd Font symbols. Any installed monospace family can replace the Latin face, and an installed CJK family can be inserted before the symbol and system fallbacks. See font-family, terminal.font-fallback-family, font-size, terminal.font-thicken, and terminal.line-height.

Global Quick TerminalCopy link

While Zshell is running, press Cmd+I or choose Terminal → Quick Terminal to show or hide its independent shell. Adjust size, opacity, and the global shortcut in Settings → Terminal → Quick Terminal.

Session behavior: Reuse workspace (default) / New workspace each time. Reuse keeps panes and tasks. New workspaces end when hidden. Mode changes apply on next show; the reusable workspace stays available when switching back. Shell history follows your shell configuration. A new workspace always starts with one empty terminal, without the previous output, pane layout or session state.

Split with the toolbar buttons Split Right / Split Down, the terminal context menu, or Cmd+D / Cmd+Shift+D. The preservation behavior below applies to reusable workspaces, including pane ratios and focus.

• Hiding with the shortcut, Esc, a click outside, or loss of focus keeps the same shell, input, scrollback, and running tasks. Open it again to continue.
• Pinning keeps the window visible when switching apps. Size, opacity, and pin state remain when hidden.
• Run exit in the shell to end the session; opening Quick Terminal again starts a fresh shell.

Enable terminal.preserve-sessions before opening a new quick terminal to keep it running after a normal Zshell quit. On relaunch, opening Quick Terminal reconnects to that live shell with either backend. Zshell → Quit and End All Sessions ends it even when hidden. macOS restarts end all sessions.

Quick Launch, which saves and runs commands, is a separate feature.

Vim command hintsCopy link

Manage hints in Settings → Terminal → Behavior → Vim command hints, then open the right sidebar's Info tab. A VIM COMMANDS section appears below the session information while Vim, Vi, or Neovim is active. It is on by default for new configurations and applies immediately to existing terminals on both backends.

The complete common-command list stays available; only its priority changes: Normal puts :w, :q, yy, and p/P first; Visual Block puts I/A, block changes, and corner movement first. Insert, Replace, Visual, Visual Line, Select, command-line, and search modes have their own ordering. Each entry names its applicable modes. Search by keys, description, or mode name; descriptions and search UI follow any of the app's 17 languages. Clear the query to restore the full list. The hints are a reference; they never send input to the editor.

Local editors are identified by their foreground executable. Inside SSH, Mosh, or a terminal multiplexer, detection uses the visible Vim mode/status line and screen layout without installing a remote plugin. Keep Vim's showmode or a recognizable status line enabled. Configurations that hide or rename mode labels can fall back to Normal hints or prevent remote detection; custom mappings are not interpreted. Only the active Info panel is sampled, and hints disappear when the foreground program changes or the editor is no longer recognizable.

You can also enable it in the configuration file with terminal.vim-command-hints = true.