# WispTerm

A fast, modern terminal for Windows and macOS, written in Zig, powered by libghostty-vt.

Download latest release View on GitHub

Ships for Windows and macOS (Apple Silicon & Intel). Linux port in progress.

wispterm — pwsh
pwsh
wsl
ssh: workstation

    PS C:\Users\you> wispterm --theme Poimandres
      loading config from %APPDATA%\wispterm\config
      fonts: Cascadia Code (DirectWrite + FreeType)
      themes: 453 built-in
      ready.

    PS C:\Users\you> git status
    On branch main
    nothing to commit, working tree clean

    PS C:\Users\you> ▌

## Built for daily work

WispTerm layers practical features on top of Ghostty's terminal core — splits, tabs, AI agent tools, a file explorer, themes, background images, and an opt-in remote-access client.

### Ghostty's emulation

Uses `libghostty-vt` for VT parsing and terminal state, so behavior matches Ghostty closely.

### Native font stack

DirectWrite font discovery with per-glyph fallback, FreeType rasterization, Ghostty-style metrics.

### Splits & tabs

Vertical/horizontal splits, tab strip, focus-follows-mouse, equalize sizes, spatial focus movement.

### AI agent tabs

Chat tabs can act as local agents: read terminal snapshots, run shell commands (PowerShell on Windows, shell on macOS), work with WSL and SSH sessions, load skills, keep tool approval inside WispTerm, and export full or clean Markdown records. Explore the AI workflow or see use cases.

### 453 themes built-in

Ghostty-compatible theme files. Defaults to Poimandres; browse previews in the theme gallery and switch from the command center.

### Background images

PNG/JPG/BMP/GIF/TGA wallpapers with per-cell opacity blending and four scaling modes.

### File explorer & previews

Browse local, WSL, and SSH files. Preview Markdown, text, CSV, TSV, and images without leaving the terminal.

### Embedded browser

Open `http(s)` URLs in a side WebView2 panel (Windows). SSH sessions tunnel loopback URLs automatically.

### Kitty Graphics

Display inline images and PDFs from remote shells via `imgcat.py` / `pdfcat.py` helpers.

### Custom shaders

Ghostty-compatible GLSL post-processing. Effects apply uniformly to terminal and wallpaper.

### Sprite rendering

Crisp box drawing, block elements, braille patterns, and powerline symbols at any size.

### Opt-in remote access

Share a session key over a Cloudflare-hosted relay. Disabled by default — your shell stays local.

### Hot-reload config

Press `Ctrl`+`,` to edit; saving applies changes without restarting.

## Install

Pre-built releases for Windows and macOS are published per version. Pick the package that fits your platform and workflow.

Windows · Recommended

### Portable

Single executable — download the zip, extract, and run `wispterm.exe`.

Latest release →
Windows · With browser

### Portable + WebView2

Bundles `WebView2Loader.dll` for the embedded browser side panel.

Latest release →
macOS · Beta

### macOS DMG

Signed and notarized `.dmg` for Apple Silicon and Intel. Requires macOS 13+. Open the DMG and drag `WispTerm.app` to Applications.

Latest release →
Source

### Build from source

Clone the repo and build with Zig. On Windows: `zig build`. On macOS: `zig build macos-app -Dtarget=aarch64-macos`.

    git clone https://github.com/xuzhougeng/wispterm
    cd wispterm
    # Windows
    zig build -Doptimize=ReleaseFast
    # macOS (Apple Silicon)
    zig build macos-app -Dtarget=aarch64-macos

## Configure with a single file

WispTerm uses a Ghostty-compatible `key = value` config. Default path: `%APPDATA%\wispterm\config` on Windows, `~/Library/Application Support/wispterm/config` on macOS. Press `Ctrl`+`,` (`Cmd`+`,` on macOS) to open it; CLI flags override file values.

    font-family            = Cascadia Code
    font-size              = 14
    cursor-style           = bar
    cursor-style-blink     = true
    theme                  = Poimandres

    window-width           = 120
    window-height          = 32
    scrollback-limit       = 10000000

    custom-shader          = path\to\shader.glsl
    background-image       = C:\Users\me\Pictures\wallpaper.png
    background-opacity     = 0.85
    background-image-mode  = fill

    # Opt-in remote access (disabled by default)
    remote-enabled         = false
    remote-server-url      = https://remote.example.com
    remote-device-name     = Workstation
    remote-session-key     = Workstation

    # AI Chat agent tools
    ai-agent-enabled       = true
    ai-agent-permission    = confirm   # confirm | full
    ai-agent-output-limit  = 16384

Run `wispterm --help` for the full flag list, or `wispterm --show-config-path` to print the resolved config path.

## Keyboard shortcuts

Defaults from `src/keybind.zig`. Modal overlays intercept keys first. `Ctrl/Cmd` means Ctrl on Windows/Linux, Cmd on macOS; `Alt/Opt` means Alt on Windows/Linux, Option on macOS. `Ctrl`+``` and `Ctrl`+`Tab` stay on Ctrl on all platforms.

Open command center `Ctrl/Cmd` `Shift` `P`
New session (launcher)`Ctrl/Cmd` `Shift` `T`
New window `Ctrl/Cmd` `Shift` `N`
Toggle tab sidebar `Ctrl/Cmd` `Shift` `B`
Toggle file explorer `Ctrl/Cmd` `Shift` `Alt/Opt` `E`
Split to the right `Ctrl/Cmd` `Shift` `O`
Equalize splits `Ctrl/Cmd` `Shift` `Z`
Close panel / tab / window `Ctrl/Cmd` `Shift` `W`
Maximize / restore window `Alt/Opt` `Enter`
Move focus by direction `Alt/Opt``←``↑``↓``→`
Previous panel `Ctrl/Cmd` `Shift``[`
Next panel `Ctrl/Cmd` `Shift``]`
Previous tab `Ctrl` `Shift` `Tab`
Next tab `Ctrl` `Tab`
Jump to tab 1–9 `Alt/Opt` `1`…`9`
Increase font size `Ctrl/Cmd``+`
Decrease font size `Ctrl/Cmd``−`
Copy selection `Ctrl/Cmd` `Shift` `C`
Paste text `Ctrl/Cmd` `V`
Paste clipboard image `Ctrl/Cmd` `Shift` `V`
Open config file `Ctrl/Cmd``,`
Show/hide Quake drop-down `Ctrl````

## FAQ

### Why isn’t my default PowerShell Administrator?

Shells inherit WispTerm’s privilege level. A normal launch uses a standard token (even for admin accounts under UAC). WispTerm does not auto-elevate new tabs.

### How do I get an elevated shell?

Right-click `wispterm.exe` or your shortcut and choose Run as administrator; new tabs in that window stay elevated. For a one-off elevated console elsewhere, use `Start-Process pwsh -Verb RunAs` (UAC prompt).

### How do I enable copy on select and paste on right-click?

Set `copy-on-select = true` and `right-click-action = paste` in your config file (`%APPDATA%\wispterm\config` on Windows, `~/Library/Application Support/wispterm/config` on macOS). If you want right-click to copy when a selection is active and paste otherwise, use `right-click-action = copy-or-paste` instead.

### How do I connect to older bastions or SSH servers?

Set `ssh-legacy-algorithms = true` in your config file. This enables compatibility options for older hosts that still require `ssh-rsa`, `ssh-dss`, legacy Diffie-Hellman key exchange, or CBC ciphers.

### Why did an SSH download or upload lose the current directory?

WispTerm can download relative SSH paths and upload dragged files into the interactive SSH shell's current directory only when the remote shell reports OSC 7. If OSC 7 is missing, helper `ssh.exe` / `scp.exe` commands start a fresh session that usually sees the login directory, not the directory you `cd`'d to. Configure your remote shell to emit OSC 7; see the setup snippets in README.

### What is the AI Chat / Agent prompt length limit?

WispTerm now allows up to `65536 bytes` for one draft in the AI Chat / Agent input box. This is the per-message input limit before you press Enter, not the full conversation context limit.

### Why does Remote mirror the local terminal size on phones?

The desktop WispTerm app is the source of truth for PTY state, Ghostty VT state, scrollback, cursor position, and split layout. The browser receives layout snapshots and output bytes from that local session, so it can rearrange panels for mobile, but it does not create an independent phone-sized terminal grid. True mobile reflow would require resizing the local terminal itself or adding a separate remote PTY/viewport model.

## Credits

- Original project: arya-s/phantty — the Zig + libghostty-vt foundation and the Windows terminal core.
- Terminal emulation: ghostty-org/ghostty via `libghostty-vt`.
- Image decoding: stb_image (vendored through the Ghostty dependency).