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 /model or 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

Versions

The desktop app version is the repository root version in build.zig.zon (currently 1.34.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+Tab is 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+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+C
Select from the last terminal click anchor	Shift-click terminal text	Shift-click terminal text
Select terminal text while tmux mouse mode is enabled	Shift-drag	Shift-drag
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
Download selected AI History raw file	D in AI History	D in AI History
Export selected AI History transcript as Markdown	M in AI History	M in AI History
Attach selected AI History transcript to Copilot	A in AI History	A in AI History
Refresh local AI History scan	R in local AI History	R in local AI History
Run Memory Digest now	D in Memory Center	D in Memory Center
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; Ctrl+Shift+V also pastes text when the clipboard has no image	Cmd+V; Cmd+Shift+V also pastes text when the clipboard has no image
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 visual settings	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 Markdown to save the full transcript, including thinking, tool details, and usage metadata.
Export AI Chat Markdown Clean to 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.34.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.20660541

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.34.0) [Computer software]. Zenodo.
https://doi.org/10.5281/zenodo.20660541

Name		Name	Last commit message	Last commit date
Latest commit History 2,974 Commits
.github		.github
assets		assets
debug		debug
docs		docs
packaging		packaging
pkg		pkg
plans		plans
plugins		plugins
release-notes		release-notes
remote		remote
shaders		shaders
src		src
tests		tests
tools		tools
vendor/glad		vendor/glad
wiki		wiki
.gitignore		.gitignore
.zenodo.json		.zenodo.json
AGENTS.md		AGENTS.md
CITATION.cff		CITATION.cff
CONTRIBUTING.md		CONTRIBUTING.md
KNOWN_ISSUES.md		KNOWN_ISSUES.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README.zh-CN.md		README.zh-CN.md
ROADMAP.md		ROADMAP.md
build.zig		build.zig
build.zig.zon		build.zig.zon
pytest.ini		pytest.ini

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

WispTerm

Features

Documentation

Versions

Building

Usage

Keyboard shortcuts

AI Chat Markdown export

SSH current directory for downloads and uploads

Credits

License

Star History

Citation

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

WispTerm

Features

Documentation

Versions

Building

Usage

Keyboard shortcuts

AI Chat Markdown export

SSH current directory for downloads and uploads

Credits

License

Star History

Citation

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages