Kterm

Kterm provides:

• A real local shell through a pseudo-terminal
• Binary vertical and horizontal splits with one independent PTY per pane
• VT/ANSI screen parsing and resize handling
• Primary device-attributes replies so interactive applications do not stall during startup
• Configurable horizontal tab stops with forward, backward, and clear operations
• Read-only OSC queries for the 256-color palette and effective foreground, background, and cursor
• All four Catppuccin flavors with matching foreground, background, cursor, accent, and 16-color ANSI palettes
• Pane-local OSC 7 and Windows OSC 9;9 working-directory tracking inherited by new splits, with automatic OSC 7 reporting for directly launched zsh sessions
• Active-pane OSC 52 writes for copying from local or SSH applications to the system clipboard
• Blinking, cell-aligned cursors with DECSCUSR shape changes used by Vim and other TUIs
• Kitty keyboard disambiguation and ConPTY Win32 input records for modified-key fidelity
• Shaped, system-font text rendered by glyphon
• A dedicated WGSL post-process pass with glow, chromatic aberration, scanlines, vignette, and noise
• A protocol-extension boundary for future custom terminal sequences
• Frame-scoped rounded rectangles with independent corners and standard VT fallbacks

See docs/vt-support-policy.md for the rationale and boundaries around tab-stop management, color queries, working-directory reporting, palette mutation, and horizontal margins.

Themes

Use a built-in theme for one launch without changing kterm.toml:

kterm --theme rose-pine-dawn
kterm --config /path/to/kterm.toml --theme catppuccin-latte

--theme has higher precedence than the selected configuration file. Run kterm --list-themes to print the accepted names one per line. The override also applies to font preview and to elevated panes on Windows.

Linux installation

Fedora and Debian/Ubuntu packages are published for x86_64 and ARM64. Install the package for the current system with:

curl -fsSLo kterm-update https://kterm.kkutsner.dev/kterm-update
bash kterm-update
rm kterm-update

Installed packages include kterm-update; run it later to download, verify, and install the newest release. See docs/linux-installation.md for version selection and removal.

Windows installer

The per-user x64 MSI installs Kterm under %LOCALAPPDATA%\Programs\Kterm, adds Start menu shortcuts for Kterm, the offline quick start, and configuration editing, and registers uninstall through Windows Installed Apps. An Uninstall Kterm Start menu shortcut is also provided. Current packages are unsigned, so Windows may show an unknown-publisher or SmartScreen warning.

Kterm creates a diagnostic log for each launch in %LOCALAPPDATA%\kterm\logs on Windows, ~/.local/share/kterm/logs on Linux, or ~/Library/Application Support/kterm/logs on macOS. Runtime errors and Rust panic backtraces are recorded there for troubleshooting. Terminal input and screen contents are not logged.

Windows builds use the GUI subsystem by default, so launching kterm.exe from File Explorer does not open a separate console window. Informational commands such as --help and --list-themes attach to the invoking terminal when one exists. Elevated Windows panes show a peach Administrator label and shield while active, and expose the same status in the native window title used by Alt+Tab and accessibility tools. The active divider or zen frame also switches from the theme accent to the same peach color.

Configuration

Create kterm.toml in the platform configuration directory and restart Kterm to apply file changes. On Windows, the installed Edit Kterm Configuration Start menu shortcut opens the first existing file in the same order Kterm uses at startup. If none exists, it creates the commented default under %APPDATA%\kterm without overwriting existing settings:

For cross-platform compatibility, Kterm checks ~/.config/kterm/kterm.toml after the native platform location. It then falls back to kterm.toml in its working directory. The repository's sample file can be copied to any listed location and customized.

Kterm configuration reference

Unknown sections and fields are rejected. Every section and field is optional; omitted values use the defaults below.

All [keybindings] values use modifier+modifier+physical-key strings. Accepted modifier names are ctrl/control, shift, alt, and super/meta/win; each modifier may appear at most once and modifiers match exactly. Accepted physical keys are a-z, 0-9, equal, minus, slash, backslash, left, right, up, down, enter, tab, space, home, end, page-up, page-down, insert, delete, numpad-add, numpad-subtract, and f1-f12. Each binding requires exactly one key. Enabled actions cannot duplicate one another or use reserved pane and paste combinations: Ctrl+H/J/K/L, Ctrl+Slash/Backslash, Ctrl+Shift+W/H/J/K/L/Arrow, and Ctrl(+Shift)+V. keybindings.restart_elevated is accepted on every platform but acts only on Windows.

Use Ctrl+Equal/Minus to adjust font size temporarily; line height scales with it and the PTY grid resizes immediately. The Windows titlebar follows at half that rate, bounded between 0.75x and 3x its startup size. The Linux custom titlebar follows the same scaling behavior. font_size, line_height, and padding are logical-pixel values and automatically follow the monitor's HiDPI scale factor.

Use Ctrl+/ to split the active pane vertically and Ctrl+\ to split it horizontally. Use Ctrl+Shift+W to close the active pane; closing the final pane exits Kterm. On Windows, use Ctrl+Shift+/ or Ctrl+Shift+\ for the corresponding elevated split. Kterm shows UAC, then hosts the administrator shell in the new pane while the rest of the window remains unelevated. Cancelling UAC leaves the existing workspace unchanged. Use Ctrl+Shift+Enter to replace the active unelevated pane with a fresh administrator shell. The pane keeps its layout and working directory, but its current shell, applications, jobs, and scrollback are terminated and cannot be restored. Cancelling UAC leaves the original pane running. See docs/windows-elevated-panes.md for the process model, security boundary, visual indicators, and limitations.

Set [picker].enabled = true to route those same split shortcuts through the bundled kterm-picker. The picker runs unelevated, preserves the new pane's identity when launching a selection, and defers UAC until after a selection made from a shifted split shortcut. Favorites come from picker.kterm.toml in Kterm's user configuration directory; copy picker.kterm.toml.example as a starting point. Escape or q cancels the split, while the initially selected Default shell entry preserves a quick split-then-Enter workflow. Use configurable Ctrl+Shift+P to open the same picker temporarily in the active pane. The current process keeps running, continues receiving pane resizes, and returns when the picker is cancelled or the selected process exits. Invoking the shortcut from a selected process creates a LIFO stack, so nested selections return in reverse order. Closing the pane still terminates the whole stack. The shortcut passes through to terminal applications while picker integration is disabled. A selected process's validated launch directory remains available to nested pickers even when that process does not emit OSC working-directory metadata. The picker displays at most ten entries at once and adds a scrollbar for longer filtered lists. Favorite names must be unique after trimming and case folding. Each favorite accepts exit_behavior = "close" (the default) or "wait-for-key" to preserve the process's final screen until a key is pressed. In an active-pane picker, that key returns to the parked process. With "wait-for-key", optional wait_for_key_on controls which outcomes pause: "always" is the default, "failure" matches nonzero exits and signals, "success" matches exit code zero, and an array such as [2, 10] matches exact exit codes. Exact-code arrays never match signal exits. wait_for_key_on is invalid with exit_behavior = "close". Unmatched outcomes return or close immediately; matching outcomes show the exit result and accept any key. Omitting working_directory is equivalent to "inherit" and starts the favorite in the directory reported by the pane from which the picker was opened. Selected processes use Kterm's environment, not runtime environment changes made inside the parked shell. Windows installations include an Edit Kterm Picker Configuration Start menu shortcut. Pass --config PATH through [picker].args to select an explicit favorites file.

Picker configuration reference

picker.kterm.toml rejects unknown fields and supports exactly version = 1 with up to 256 [[favorites]] entries.

Set [kgit].enabled = true to make configurable Ctrl+Shift+G launch kgit temporarily in the active pane. Kterm passes the active pane's validated local directory as the exact argument array kgit --repo <directory>; configured [kgit].args are inserted before --repo. The shell or application already in the pane stays parked and returns immediately when kgit exits successfully. On a nonzero or signal exit, Kterm preserves kgit's final screen, displays the outcome, and waits for any key before returning to the parked process. If integration is disabled or the pane has no trustworthy local working-directory metadata, the shortcut passes through unchanged. A launch failure leaves the current process in place and is written to Kterm's diagnostic log. Configure the executable and shortcut with:

[kgit]
enabled = true
program = "kgit"
args = []

[keybindings]
kgit_open = "ctrl+shift+g"

Navigate to the nearest pane with Ctrl+H/J/K/L, and move the active pane's nearest divider with Ctrl+Shift+H/J/K/L. Ctrl+Shift+Arrow remains an alternative resize binding. Each split assigns roughly 70% of its space to the branch containing the active pane. Inactive PTYs preserve columns for vertical previews or rows for horizontal previews, resize only the orthogonal dimension, and then scale uniformly to fill the smaller viewport. Click a pane to focus it, or drag any separator on the active pane's split path to resize it with the mouse. The cursor changes to show the divider's resize direction. Point at a pane, then hold Ctrl+Shift and scroll up or down to grow or shrink that pane along all available axes without changing focus. In zen mode, scrolling over the active floating pane changes the viewport size. Set panes.mouse_wheel_resize = false to disable this gesture and leave Ctrl+Shift wheel events to the normal terminal wheel path. Swap the active pane with its nearest neighbor using configurable Ctrl+Alt+H/J/K/L. Alternatively, hold Ctrl+Shift, press the left mouse button inside any pane, and drag it onto another pane. A subtle animated accent wash marks the source and target, and the two pane sessions exchange locations when the button is released. Dragging an inactive pane does not activate it; the currently active session remains active even when its location participates in the swap. Dropping outside another pane cancels the operation. Drag across terminal text to select it; releasing the mouse copies the selection to the system clipboard. When an application enables mouse reporting, mouse buttons and requested button/any-motion events are sent to the application instead; hold Shift while dragging to select text. Paste clipboard text with Ctrl+V, Ctrl+Shift+V, or Shift+Insert; applications that enable bracketed paste receive the standard paste delimiters. With an active mouse selection, Ctrl+C copies and clears the selection instead of sending an interrupt; without a selection it retains normal terminal interrupt behavior.

Set [panes].zoom_mode to "default" for scaled inactive previews, "none" to render every pane at the configured font size, or "zen" to place the active pane in an accent-framed viewport centered over the default previews. Press Ctrl+Shift+Z to cycle through these modes at runtime; the shortcut can be reassigned with keybindings.zoom_mode_cycle. Zen mode uses the full terminal area when no inactive panes exist. In zen mode, Ctrl+Shift+Equal/Minus changes the floating viewport percentage instead of resizing the underlying split tree, while directional pane-resize shortcuts are disabled.

Kterm automatically injects minimal prompt integration into directly launched PowerShell and zsh sessions without replacing the user's normal startup files. The prompt boundary recovers the primary screen and pane shortcuts when a foreground alternate-screen application is killed before it can restore terminal state. The zsh integration also emits OSC 7 when the prompt is displayed, allowing new splits to inherit the active pane's current local directory. Shells started from another shell, terminal multiplexers, and remote shells must provide their own integration.

OSC 52 clipboard writes are enabled by default for the active pane. This allows applications such as remote Neovim or tmux sessions to copy into the shared system clipboard. After copying, switch to any other local or SSH pane and use Kterm's normal paste shortcut; the reverse workflow is identical. Mouse selections also use the same clipboard. Configure this under [clipboard] with osc52_write and osc52_max_bytes. Clipboard queries remain unsupported, so applications cannot silently read local clipboard contents; Ctrl+V is the explicit user-authorized read path.

Use Ctrl+Shift+Equal/Minus to grow or shrink the active pane along both available dimensions. Kterm adjusts the nearest vertical and horizontal splits independently. Font zoom and all-dimension pane sizing can be reassigned under [keybindings]; bindings use physical key names and exact modifiers, and conflicting bindings are rejected at startup. Set [panes].resize_step_percent to control the percentage-point increment used by all pane resize shortcuts; it defaults to 2.

Alternate-screen applications that explicitly claim cooperative pane controls receive the H/J/K/L controls first, allowing editors such as Neovim and Kvim to navigate or resize their own splits and hand the same action to Kterm at an editor edge. Other full-screen applications leave the shortcuts with Kterm. See docs/seamless-pane-navigation.md for the cooperative protocol and Neovim setup. The native window title follows standard OSC 0/2 title updates from the active pane; titles emitted by inactive panes remain pane-local until that pane is selected. On Windows, an OSC title that is an exact executable path is replaced with the program's version-resource name. The window icon always follows the active pane's shell process. Windows and Linux use a client-rendered titlebar so the terminal's actual post-processed background continues behind its title, icon, and caption controls; native window dragging and resizing remain available through the window manager or compositor. Set window.decorations = "native" to use native decorations instead, which can be useful with tiling window managers. On macOS, the terminal background extends through the transparent native titlebar while terminal rows remain below the window controls. On Windows and Linux, ConEmu OSC 9;4 progress updates replace the custom-titlebar icon with a bounded progress indicator; indeterminate progress animates and stale progress clears after 15 seconds.

terminal.theme accepts all four Catppuccin flavors (catppuccin-latte, catppuccin-frappe, catppuccin-macchiato, and catppuccin-mocha) and all three Rosé Pine flavors (rose-pine, rose-pine-moon, and rose-pine-dawn), and six Everforest variants combining dark or light with hard, medium, or soft contrast (for example, everforest-dark-medium). Catppuccin Mocha remains the default. Each flavor supplies a coordinated terminal foreground, background, cursor, accent, surface, and 16-color ANSI palette. The Everforest colors and ANSI mapping are based on Everforest by sainnhe under the MIT license; Kterm maps its primary status-line accent to the cursor and active-pane accent. Kterm substitutes contrast-safe Everforest foreground shades for grayscale ANSI slots that upstream assigns background-layer colors, because shells and terminal applications commonly render those slots as text. See the third-party theme notices. Catppuccin Latte, Rosé Pine Dawn, and all Everforest light variants request light native window chrome. Optional foreground and background CSS-style "#RRGGBB" values in [terminal] override those two theme colors. Optional window.background independently sets the backdrop visible around pane grids and behind custom window chrome; it defaults to the effective terminal background. Background and theme changes require a restart. For temporary launches, --theme NAME overrides terminal.theme without editing the file.

Visual effects

The [effects] settings combine a full-image shader pass with accent geometry. glow_strength controls shader bloom around terminal content and overlays, while glow_radius sets its sampling distance; a zero strength disables bloom regardless of radius. Chromatic aberration offsets red and blue horizontally, scanlines darken alternating rows, vignette darkens the window edges, and noise adds per-pixel brightness variation. Setting any of those effect strengths or offsets to zero disables that effect.

Active-pane dividers and the zen pane frame have their own feathered accent halos. Their base spread and intensity are independent of glow_strength, glow_radius, and cursor_glow, although enabling shader bloom also blooms those rendered accents.

Kterm embeds the thin, thin italic, regular, italic, bold, and bold italic faces of JetBrainsMono Nerd Font Mono, so its default font works without a host font installation. It also embeds Symbols Nerd Font Mono and uses it explicitly for private-use Nerd Font glyphs, so terminal.font_family can name any installed monospace font without losing prompt icons. Run kterm --preview-fonts to browse exact family names in colored regular, thin, italic, and bold terminal cards. A scrollbar tracks the visible range; use the mouse wheel or Page Up/Down to page through the installed fonts.