ghostty-web

@xgent-ai/ghostty-web is a fork of coder/ghostty-web that builds on the upstream libghostty-vt C API (no Ghostty patches) and tracks recent Ghostty releases.

Ghostty for the web with xterm.js API compatibility — giving you a proper VT100 implementation in the browser.

• Migrate from xterm by changing your import: @xterm/xterm → @xgent-ai/ghostty-web
• WASM-compiled parser from Ghostty—the same code that runs the native app
• Zero runtime dependencies, ~800KB WASM bundle (~280KB gzipped)

Originally created for Mux (a desktop app for isolated, parallel agentic development), but designed to be used anywhere.

Try It

• Live Demo on an ephemeral VM (thank you to Greg from disco.cloud for hosting).

• On your computer:

  npx @ghostty-web/demo@next   # upstream coder/ghostty-web demo

  This starts a loopback-only HTTP server with a real shell on http://127.0.0.1:8080. The demo protects /ws with a per-run same-origin token and rejects cross-origin WebSocket handshakes. Works best on Linux and macOS.

  To intentionally bind somewhere else, set HOST=<host>. If you serve the demo through extra hostnames or a wildcard bind such as HOST=0.0.0.0, also set GHOSTTY_ALLOWED_HOSTS=host1,host2. Avoid remote exposure unless you understand the risk: the demo starts a real local shell.

Comparison with xterm.js

xterm.js is everywhere—VS Code, Hyper, countless web terminals. But it has fundamental issues:

| Issue | xterm.js | ghostty-web | | ---------------------------------------- | ---------------------------------------------------------------- | -------------------------- | | Complex scripts (Devanagari, Arabic) | Rendering issues | ✓ Proper grapheme handling | | XTPUSHSGR/XTPOPSGR | Not supported | ✓ Full support |

xterm.js reimplements terminal emulation in JavaScript. Every escape sequence, every edge case, every Unicode quirk—all hand-coded. Ghostty's emulator is the same battle-tested code that runs the native Ghostty app.

Installation

npm install @xgent-ai/ghostty-web

Usage

ghostty-web aims to be API-compatible with the xterm.js API.

import { init, Terminal } from '@xgent-ai/ghostty-web';

await init();

const term = new Terminal({
  fontSize: 14,
  theme: {
    background: '#1a1b26',
    foreground: '#a9b1d6',
  },
});

term.open(document.getElementById('terminal'));
term.onData((data) => websocket.send(data));
websocket.onmessage = (e) => term.write(e.data);

For a comprehensive client <-> server example, refer to the demo.

Development

ghostty-web builds ghostty-vt.wasm from the pinned Ghostty submodule with upstream's own libghostty-vt WebAssembly target and C API — no patches. Struct layouts and enum values are read at load time from the library's ghostty_type_json() description.

Requires Zig (the version in ghostty/build.zig.zon, currently 0.16.0) and Bun.

bun run build

To move to a newer Ghostty, update the submodule and rebuild:

git -C ghostty fetch --depth 1 origin <commit> && git -C ghostty checkout <commit>
bun run build:wasm && bun test

If Zig cannot download dependencies (for example behind some HTTPS proxies), scripts/build-wasm.sh falls back to downloading them with curl and adding them with zig fetch, which verifies each archive against the hashes in build.zig.zon.

Mitchell Hashimoto (author of Ghostty) has been working on libghostty which makes this all possible.

This library will eventually consume a native Ghostty WASM distribution once available, and will continue to provide an xterm.js compatible API.

At Coder we're big fans of Ghostty, so kudos to that team for all the amazing work.

License

MIT