# WispTerm: a Zig terminal workspace built on libghostty-vt for remote development and AI agents

> WispTerm wraps Ghostty's VT engine in a cross-platform workspace with file previews, SSH port forwarding and AI agent tabs. It ships for Windows and macOS, with Linux still labelled experimental.

**xuzhougeng/wispterm** — A cross-platform terminal workspace for remote development and AI agent workflows, powered by libghostty-vt

- Repository: https://github.com/xuzhougeng/wispterm
- Website: https://wispterm.com/
- Stars: 420 · Forks: 25
- Language: Zig
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/xuzhougeng-wispterm

## The gap WispTerm is trying to fill: terminals that stop at the prompt

Most terminals end at the shell. You get a PTY, a scrollback buffer and a set of keybindings, and everything else (browsing a remote directory, previewing a Markdown file, keeping an SSH tunnel alive, talking to a coding agent) happens in another window or another tool. WispTerm's README frames the project as a cross-platform terminal workspace for remote development and AI agent workflows, and the feature list reads like an attempt to pull those adjacent tasks into the terminal window itself.

The target user is fairly specific. If you SSH into a remote box, run WSL on Windows, or drive an OpenAI-compatible agent from a terminal tab, the bundled File Explorer, previews, port forwarding manager and AI Agent sessions are aimed at you. If you just want a fast local shell, most of that surface area is dead weight, and the README does not present a minimal mode.

It is written in Zig and uses libghostty-vt for terminal emulation, so the VT parsing and terminal state are Ghostty's, not a from-scratch implementation. That choice matters more than the language: theme compatibility, font metrics and rendering behaviour inherit from a project with its own conventions.

## How the pieces fit: libghostty-vt, FreeType, and a WebView panel

The README describes a layered stack. libghostty-vt handles VT parsing and terminal state. Native font discovery runs through DirectWrite on Windows, CoreText on macOS or fontconfig on Linux, with per-glyph fallback when a character is missing from the chosen font. FreeType does glyph rasterization with Ghostty-style font metrics, and a separate sprite path draws box drawing, block elements, braille patterns and powerline symbols. Themes come from Ghostty-compatible theme files, with more than 450 built in and Poimandres as the default.

Some features are platform-conditional rather than universal. The embedded browser panel opens web URLs in a side WebView2 panel on Windows or WKWebView on macOS, and the README qualifies it with when available. That panel is also what makes persistent SSH loopback port forwarding for profile sessions possible. Remote access is opt-in and disabled by default, sharing a session key over a Cloudflare-hosted relay.

The versioning is split in a way that will confuse people reading release notes. The desktop app version is the repository root version in build.zig.zon, currently 1.38.0, and that is what wispterm --version reports. The WispTerm Remote web console and relay under remote/ carries an independent npm/web version, currently 0.32.0, and desktop releases do not require a Remote bump unless the release touches remote/. Two version numbers, two release cadences.

## Installing WispTerm and running a first AI agent tab

The README does not give a package-manager install line for either platform. It points at the releases page for downloads and documents building from source. On Windows the documented flow is a direct zig build from PowerShell:

```powershell
zig build                         # Debug build for development
zig build -Doptimize=ReleaseFast  # ReleaseFast build for distribution
```

The README notes a Makefile may still exist as a convenience wrapper, but says normal Windows development should use PowerShell and direct zig commands. On macOS the documented path requires macOS 13+ and Zig 0.15.2, and produces an .app bundle:

```bash
zig build macos-app -Dtarget=aarch64-macos   # Apple Silicon (use x86_64-macos on Intel)
open zig-out/bin/WispTerm.app
```

Once built, the binary takes CLI flags. Passing flags on macOS requires the binary path rather than launching the app bundle. The README lists the available options, including the font and theme flags shown here:

```bash
wispterm --font <name> --theme <path>
```

For a first real use, the AI Agent sessions feature is the one with the most moving parts. The README says agent tabs are OpenAI-compatible, configured through profiles, with history restore, Markdown transcript export and local skill distillation. It does not document the profile schema in the README itself; that lives in docs/ai-agent.md. The in-session model switch is documented as /model or a click on the model label, which hands the session to another saved profile with a context summary. If a Copilot request is already running, submitted prompts queue and auto-send in order when the session goes idle, and the queue panel lets you reorder, edit or drop entries.

## Where WispTerm is the wrong tool

Linux is the clearest boundary. The README labels the Linux AppImage as published for community testing and experimental, while Windows and macOS are marked supported. The Makefile confirms the split: test-macos-e2e builds a macOS .app plus wisptermctl and runs pytest against tests/macos_e2e, while test-linux-e2e builds an x86_64-linux-gnu binary and wisptermctl and runs the same test directory. The Linux target needs DISPLAY set, and xdotool is described as optional because the control-channel tests still run without it. That is a thinner story than the macOS path, which the Makefile says needs Accessibility permission granted to the running terminal and pins /usr/bin/python3 because its user-site carries PyObjC.

The embedded browser panel is conditional by design. The README says it opens when available, which means URL previews and the loopback forwarding that depends on it are not guaranteed on every configuration. Remote access is off unless you turn it on, and enabling it means sharing a session key through a Cloudflare-hosted relay, which is a decision about trust rather than a feature toggle.

Finally, this is not a drop-in replacement for a scriptable terminal. The CLI surface documented in the README is presentation-oriented (font, font style, cursor style, cursor blink, theme, background image). There is no documented headless or multiplexer mode, so tmux-style automation workflows have no obvious entry point here.

## WispTerm versus a plain Ghostty setup

The honest comparison is not against another AI terminal; it is against Ghostty itself. Ghostty gives you the VT engine and the theme format. WispTerm reuses the engine through libghostty-vt and keeps the theme files compatible, then adds the workspace layer: splits and tabs with focus-follows-mouse and equalize sizes, file browsing across local, WSL and SSH with inline previews for Markdown, text, tables, images and PDFs, a dedicated SSH port forwarding tab, an AI history browser that reads Codex, Claude Code, Kimi Code and OpenCode histories and resumes sessions from their original project directories, and workspace recipes that save a tab/split layout as a named recipe and export it as JSON.

The difference in approach is where state lives. A plain Ghostty plus tmux plus a file manager keeps each concern in its own process, and you can replace any one of them. WispTerm puts them behind one window and one configuration surface, which is faster to set up and harder to partially adopt. If you want the file previews without the AI tabs, the README does not describe a way to disable individual panels.

One shared detail worth noting: the Makefile includes an update-ghostty target that runs zig fetch --save=ghostty against the ghostty main branch tarball. WispTerm tracks Ghostty from main rather than a pinned release, so upstream churn can reach this project through that dependency.

## Maintenance, licence and what a version bump costs you

The repository is not archived, and the last push was on 2026-09-10. Releases have been frequent and small: v1.36.0 on 2026-08-29, v1.37.0 on 2026-09-05 and v1.38.0 on 2026-09-10, each roughly a week apart. That cadence is a real cost for anyone pinning versions, because the desktop version lives in build.zig.zon and moves with every release while the remote/ web console has its own version that usually does not move.

The licence is MIT, which permits commercial and closed-source use and requires preserving the copyright notice and licence text. That is the whole of the licence implication from the repository metadata; this is not legal advice, and if you redistribute a build you should read LICENSE yourself rather than take a summary.

Upgrade cost concentrates in two places. The Ghostty dependency is fetched from main, so a rebuild can pull upstream changes you did not ask for. And the theme format is Ghostty-compatible, which is good for portability but means theme behaviour is tied to that upstream rather than to WispTerm's own release cycle. The repository carries KNOWN_ISSUES.md and a docs/faq.md, which is where the project itself expects you to look before reporting a problem.

## Conclusion

Adopt WispTerm if you already live in Ghostty themes and want file previews, SSH forwarding and AI agent tabs inside one window on Windows or macOS. Skip it if you need a production Linux build or a plain, scriptable terminal, since the Linux AppImage is published for community testing and remains experimental. Verify first that your Zig toolchain matches the documented requirement of Zig 0.15.2 for macOS builds, and check docs/faq.md and KNOWN_ISSUES.md before filing a bug against a release.

## FAQ

### Which platforms does WispTerm support?

The README says WispTerm ships for Windows and macOS, including Apple Silicon and Intel, and that a Linux AppImage is published for community testing and remains experimental.

### How do I build WispTerm from source on macOS?

The README documents macOS 13+ and Zig 0.15.2, with zig build macos-app -Dtarget=aarch64-macos for Apple Silicon and x86_64-macos on Intel, then open zig-out/bin/WispTerm.app to launch it.

### Does WispTerm require a paid service or an account?

The README does not mention accounts or paid tiers. AI Agent sessions are described as OpenAI-compatible and configured through profiles, and the opt-in remote access feature shares a session key over a Cloudflare-hosted relay and is disabled by default.

## Sources

- [License: MIT](https://github.com/xuzhougeng/wispterm/blob/main/LICENSE)
- [Project website](https://wispterm.com/)
- [README](https://github.com/xuzhougeng/wispterm/blob/main/README.md)
- [Releases](https://github.com/xuzhougeng/wispterm/releases)
- [xuzhougeng/wispterm on GitHub](https://github.com/xuzhougeng/wispterm)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/xuzhougeng-wispterm