WispTerm
June 24, 2026 · View on GitHub
English | 简体中文
WispTerm
WispTerm is a cross-platform terminal workspace for remote development and AI agent workflows. It is written in Zig and powered by libghostty-vt for terminal emulation.
Note
WispTerm ships for Windows and macOS (Apple Silicon and Intel). A Linux AppImage is published for community testing and remains experimental.
Features
- Ghostty's terminal emulation - uses libghostty-vt for VT parsing and terminal state
- Native font discovery - find system fonts by name via DirectWrite, CoreText, or fontconfig, with per-glyph fallback for missing characters
- FreeType rendering - high-quality glyph rasterization with Ghostty-style font metrics
- Sprite rendering - box drawing, block elements, braille patterns, powerline symbols
- Theme support - Ghostty-compatible theme files, 450+ themes built in (default: Poimandres)
- Background image and shaders - wallpaper blending plus Ghostty-compatible GLSL post-processing
- Splits and tabs - vertical/horizontal splits, tab strip, focus-follows-mouse, equalize sizes
- File Explorer and previews - browse local, WSL, and SSH files; preview Markdown/text/tables/images/PDFs without leaving the terminal
- Embedded browser panel - open web URLs in a side WebView2 (Windows) or WKWebView (macOS) panel when available, with persistent SSH loopback port forwarding for profile sessions
- SSH port forwarding manager - silently manage local and reverse SSH forwarding rules from a dedicated tab
- AI Agent sessions - launch OpenAI-compatible Agent tabs, configure profiles, restore history, export Markdown transcripts, and distill reusable local skills
- Command-center Copilot History - search saved AI Chat and Copilot sidebar conversations, grouped by date, with source filters for sidebar vs tab sessions
- In-session model switching - use
/modelor click the model label to move an active AI chat/Copilot session to another saved profile with a context summary handoff - AI history browser - browse local, WSL, and SSH Codex / Claude Code / Reasonix history and resume sessions from their original project directories
- Kitty Graphics protocol - display inline images and PDFs from remote shells via
imgcat.py/pdfcat.py - Opt-in remote access - share a session key over a Cloudflare-hosted relay (disabled by default)
Documentation
- Configuration
- File Explorer and previews
- AI Agent sessions
- Media, background images, and inline remote images
- SSH port forwarding
- Development, architecture, packaging, and releases
- FAQ
Versions
The desktop app version is the repository root version in build.zig.zon
(currently 1.29.0) and is what wispterm --version, release notes, desktop
packages, and the command center Version entry use.
The WispTerm Remote web console/relay under remote/ has an independent npm/web
version (currently 0.32.0). Desktop releases do not require a Remote version
bump unless the release explicitly includes changes under remote/.
Building
Windows (PowerShell):
zig build # Debug build for development
zig build -Doptimize=ReleaseFast # ReleaseFast build for distribution
Remove-Item -Recurse -Force .\zig-out, .\.zig-cache -ErrorAction SilentlyContinue
macOS (requires macOS 13+ and Zig 0.15.2):
zig build macos-app -Dtarget=aarch64-macos # Apple Silicon .app bundle (use x86_64-macos on Intel)
open zig-out/bin/WispTerm.app # launch the built app
The Makefile may still exist as a convenience wrapper, but normal Windows
development should use PowerShell and direct zig commands.
For architecture, packaging, and release details, see Development, architecture, packaging, and releases.
Usage
On Windows run wispterm.exe; on macOS run WispTerm.app/Contents/MacOS/wispterm (or launch WispTerm.app directly — passing CLI flags requires the binary path).
wispterm [options]
Options:
--font, -f <name> Set font (default: embedded fallback)
--font-style <style> Font weight (default: regular)
Options: thin, extra-light, light, regular,
medium, semi-bold, bold, extra-bold, black
--cursor-style <style> Cursor shape (default: block)
Options: block, bar, underline, block_hollow
--cursor-style-blink <bool> Enable cursor blinking (default: true)
--theme <path> Load a Ghostty theme file
--background-image <path> Image file to render behind the terminal
--background-opacity <0..1> Opacity of theme/cell backgrounds (default: 1.0)
--background-image-mode <m> fill | fit | center | tile (default: fill)
--window-height <rows> Initial window height in cells (default: 0=auto, min: 4)
--window-width <cols> Initial window width in cells (default: 0=auto, min: 10)
--quake-mode <bool> Enable Quake-style drop-down mode (default: true)
--keybind <binding> Configure a shortcut, e.g. global:ctrl+backquote=toggle_quake
--config <path> Use this file as the main config
--config-path <path> Alias for --config
--config-file <path> Include another config file (prefix ? for optional)
--version, -v Print the WispTerm version and exit
--show-config-path Print the resolved main config path
--list-fonts List available system fonts
--list-themes List available themes
--test-font-discovery Test platform font discovery
--help, -h Show help
Configuration file details are in Configuration.
Keyboard shortcuts
Default app-level chords are defined in src/keybind.zig and can be remapped with repeated keybind = ... lines in the config file. Some modal/editor-local keys are still handled by the focused overlay first (command center navigation, session launcher editing, AI Chat input, and similar).
Example remaps:
keybind = alt+f10=toggle_command_palette
keybind = global:ctrl+backquote=toggle_quake
Use keybind = clear before custom bindings if you want to remove all defaults and rebuild the table from scratch. To confirm the running desktop version, open the command center (Ctrl+Shift+P on Windows, Cmd+Shift+P on macOS), type version, and press Enter.
macOS modifier mapping: most shortcuts use Cmd in place of Ctrl and Opt in place of Alt. Two exceptions keep Ctrl to avoid colliding with system shortcuts: **Ctrl+
** (Quake —Cmd+`` is the system window cycler) and Ctrl+Tab / Ctrl+Shift+Tab (tab switching —Cmd+Tabis the system app switcher).
| Action | Windows / Linux | macOS |
|---|---|---|
| Show/hide Quake drop-down | Ctrl+` | Ctrl+` |
| Open command center | Ctrl+Shift+P | Cmd+Shift+P |
| New session (session launcher) | Ctrl+Shift+T | Cmd+Shift+T |
| New window | Ctrl+Shift+N | Cmd+Shift+N |
| Toggle tab sidebar | Ctrl+Shift+B | Cmd+Shift+B |
| Split to the right | Ctrl+Shift++ | Cmd+Shift++ |
| Split downward | Ctrl+Shift+- | Cmd+Shift+- |
| Toggle file explorer sidebar | Ctrl+Shift+Alt+E | Cmd+Shift+Opt+E |
| Toggle AI Copilot sidebar (current terminal) | Ctrl+Shift+A | Cmd+Shift+A |
| Preview files (Ctrl/Cmd-click in terminal, or double-click in File Explorer) | Ctrl-click | Cmd-click |
| Previous / next image/PDF in gallery (preview focused) | Left / Right | Left / Right |
| Previous / next PDF page (PDF preview focused) | PageUp / PageDown | PageUp / PageDown |
| Download SSH remote file | Ctrl+Shift-click path in SSH output | Cmd+Shift-click path in SSH output |
| Close focused panel, tab, or window | Ctrl+Shift+W | Cmd+Shift+W |
| Maximize or restore window | Alt+Enter | Opt+Enter |
| Increase / decrease font size | Ctrl++ / Ctrl+- | Cmd++ / Cmd+- |
| Copy terminal selection or AI Chat selection/transcript | Ctrl+Shift+C | Cmd+Shift+C |
| Select from the last terminal click anchor | Shift-click terminal text | Shift-click terminal text |
| Select part of an AI answer | Drag AI answer text | Drag AI answer text |
| Select and copy part of an AI answer | Shift-drag AI answer text | Shift-drag AI answer text |
| Select AI Chat input; select transcript when input is empty | Ctrl+A in AI Chat | Cmd+A in AI Chat |
| Copy AI Chat selection or full transcript | Ctrl+C in AI Chat | Cmd+C in AI Chat |
| Delete the selected saved Agent session | D / Delete in Agent History | D / Delete in Agent History |
| Search saved Copilot History | Type / Backspace in command-center Copilot History | Type / Backspace in command-center Copilot History |
| Cycle Copilot History source filter | Tab in command-center Copilot History | Tab in command-center Copilot History |
| Move selected Copilot History row | Up / Down in command-center Copilot History | Up / Down in command-center Copilot History |
| Reopen selected Copilot History row | Enter in command-center Copilot History | Enter in command-center Copilot History |
| Delete selected Copilot History row | Delete in command-center Copilot History | Delete in command-center Copilot History |
| Edit AI History filter | Type / Backspace in AI History | Type / Backspace in AI History |
| Move selected AI History session | Up / Down in AI History | Up / Down in AI History |
| Resume selected AI History session | Enter in AI History | Enter in AI History |
| Preview selected AI History transcript | Space in AI History | Space in AI History |
| Refresh local AI History scan | R in local AI History | R in local AI History |
| Edit AI Chat input cursor | Left/Right/Home/End/Delete/Backspace | Left/Right/Home/End/Delete/Backspace |
| Stop in-flight AI Chat or Agent request | Esc in AI Chat while working | Esc in AI Chat while working |
| Copy selection (right-click) | Right-click a selection | Right-click a selection |
| Paste text | Ctrl+V | Cmd+V |
| Paste clipboard image | Ctrl+Shift+V | Cmd+Shift+V |
| Move focus to adjacent panel | Alt + arrow keys | Opt + arrow keys |
| Focus panel 1–9 by number | Ctrl+1–9 | Cmd+1–9 |
| Focus previous panel (cycle) | Ctrl+Shift+[ | Cmd+Shift+[ |
| Focus next panel (cycle) | Ctrl+Shift+] | Cmd+Shift+] |
| Equalize split sizes | Ctrl+Shift+Z | Cmd+Shift+Z |
| Next tab | Ctrl+Tab | Ctrl+Tab |
| Previous tab | Ctrl+Shift+Tab | Ctrl+Shift+Tab |
| Switch to tab 1–9 | Alt+1–9 | Opt+1–9 |
| Open config file | Ctrl+, | Cmd+, |
AI Chat Markdown export
In an active AI Chat or Agent tab, open the command center with Ctrl+Shift+P
and run:
Export AI Chat Markdownto save the full transcript, including thinking, tool details, and usage metadata.Export AI Chat Markdown Cleanto save a publishing-friendly Markdown file with only the user inputs and the final AI answer.
WispTerm opens a save dialog with a .md filename. After saving, the
saved path is copied to the clipboard.
SSH current directory for downloads and uploads
WispTerm can download a relative file path from an SSH terminal output, and upload dragged files into the interactive SSH shell's current directory, only when the remote shell reports its current directory with OSC 7. This is the same terminal convention used by Ghostty shell integration.
If OSC 7 is missing, helper ssh.exe / scp.exe commands start a fresh SSH
session and usually see the login directory, not the directory you cd'd to in
the interactive shell. In that case WispTerm shows SSH cwd unknown; click for setup instead of guessing ~/file.
Add one of these snippets to the remote shell startup file, then start a new WispTerm SSH session.
For Bash, add this to ~/.bashrc:
__wispterm_report_cwd() {
printf '\033]7;file://%s%s\a' "${HOSTNAME:-localhost}" "$PWD"
}
PROMPT_COMMAND="__wispterm_report_cwd${PROMPT_COMMAND:+;$PROMPT_COMMAND}"
For Zsh, add this to ~/.zshrc:
__wispterm_report_cwd() {
printf '\033]7;file://%s%s\a' "${HOST:-localhost}" "$PWD"
}
autoload -Uz add-zsh-hook
add-zsh-hook chpwd __wispterm_report_cwd
add-zsh-hook precmd __wispterm_report_cwd
For Fish, add this to ~/.config/fish/config.fish:
function __wispterm_report_cwd --on-variable PWD
printf '\e]7;file://%s%s\a' (hostname) (string escape --style=url $PWD)
end
__wispterm_report_cwd
Credits
- Original project: arya-s/phantty - the Zig + libghostty-vt foundation and the Windows terminal core. WispTerm builds on that base and layers additional features on top: an embedded browser panel, a file explorer with Markdown/text/table/image/PDF preview, AI Agent sessions with Markdown export, an opt-in remote-access client, Kitty Graphics image protocol support, and a configurable background image.
- Terminal emulation: ghostty-org/ghostty
via
libghostty-vt. - Image decoding: stb_image (vendored through the ghostty dependency).
License
MIT
Star History
Citation
Xu, Z.-G. (2026). WispTerm (Version 1.29.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.20660542
Copyable acknowledgment template:
We used WispTerm as part of our computational environment for life sciences data
analysis, remote computing workflows, reproducible command-line processing, and
the organization of related literature and analysis code.
Xu, Z.-G. (2026). WispTerm (Version 1.29.0) [Computer software]. Zenodo.
https://doi.org/10.5281/zenodo.20660542