Ghostty Terminal

A VS Code extension powered by @gespenst/core and Ghostty's WASM terminal engine. The terminal renders inside a VS Code WebviewPanel and connects to a real shell process via node-pty.

Features

• Full terminal emulator using Ghostty's battle-tested VT100 parser compiled to WASM
• Multiple simultaneous terminal instances
• Configurable shell, font, cursor, scrollback, and color themes
• Built-in themes: Dark, Light, Tokyo Night, Dracula, Solarized Dark
• Inherits VS Code's terminal.integrated.fontSize and terminal.integrated.fontFamily by default
• Live config updates (font, theme, cursor changes apply immediately)
• Full-scrollback find with match counts, case sensitivity, whole-word matching, and regular expressions
• HTTP(S) links opened in your browser with Cmd-click on macOS or Ctrl-click on Windows/Linux
• Text and rich clipboard paste, including images in terminal applications supporting Kitty clipboard mode 5522

Installation

npm install
npm run build

Then press F5 in VS Code to launch the Extension Development Host.

Usage

• Command Palette (Cmd+Shift+P / Ctrl+Shift+P):
  • Ghostty Terminal: New Terminal — open a new terminal
  • Ghostty Terminal: Clear Active Terminal — clear the active terminal
  • Ghostty Terminal: Kill Active Terminal — kill the active terminal
  • Ghostty Terminal: Focus Active Terminal — focus the active terminal
  • Ghostty Terminal: Find — search the active terminal, including its scrollback
• Keyboard shortcut: Cmd+Shift+`` (macOS) / Ctrl+Shift+`` (Windows/Linux) — new terminal

Inside a Ghostty terminal, press Cmd+F / Ctrl+F to open Find. Enter goes to the next match, Shift+Enter goes to the previous match, and Escape closes Find and returns focus to the terminal. Search queries stay with their terminal while it is open, including after the shell exits.

Use Cmd+C on macOS or Ctrl+Shift+C on Windows/Linux to copy a selection through VS Code. Paste uses the native clipboard event and honors bracketed-paste mode. If text could execute commands without bracketed-paste protection, VS Code asks you to review it before pasting. Images require a terminal application supporting Kitty mode 5522; ordinary shells receive the text representation, when one is available. Clipboard transactions are limited to 32 MiB and expire after 30 seconds. Remote terminal clipboard writes remain disabled.

Configuration

All settings are under the ghosttyTerminal namespace.

Architecture

Extension Host (Node.js)                Webview (Chromium sandbox)
┌─────────────────────────┐             ┌─────────────────────────┐
│  GhosttyTerminalManager │             │  @gespenst/core         │
│  GhosttyTerminalPanel   │ ◄─────────► │  Ghostty + callback WASM│
│  PtyBridge (node-pty)   │ postMessage │  Search / links / paste │
└─────────────────────────┘             └─────────────────────────┘

• Extension host spawns the shell via node-pty and manages the WebviewPanel
• Webview uses Gespenst's native API, automatic sizing, and WebGPU → WebGL2 → Canvas 2D renderer fallback
• Communication is via VS Code's postMessage API
• The shell starts only after the webview, WASM, and addons are ready and the initial grid is measured
• Rendering runs on the webview's main thread (worker: false) to fit VS Code's worker-loading restrictions
• Both compatible WASM artifacts ship with the extension; no CDN or network access is needed to start a terminal
• Gespenst packages are pinned together to 0.1.2. Update and test them together, including their WASM assets

Known Limitations

• The terminal appears in the editor area as a WebviewPanel, not in VS Code's native terminal tab bar
• Does not appear in vscode.window.terminals (not accessible by other extensions)
• File drag & drop from Finder/Explorer does not work (webview sandbox blocks file path access)
• Requires macOS, Linux, or Windows 10 build 18309+ (ConPTY)
• Does not support VS Code for the Web (node-pty requires native Node.js)

Development

Use Node.js 22.12 or later and npm. The extension continues to support desktop VS Code 1.85+.

npm ci
npm run build    # one-time build
npm run watch    # rebuild JavaScript and CSS on changes
npm run compile  # type-check extension and webview
npm test         # host/adapter unit tests
npx playwright install chromium
npm run test:browser  # real WASM + addons, auto renderer and forced Canvas fallback
npm run test:vscode   # isolated desktop VS Code smoke test; downloads stable if needed
npm run package      # create a local VSIX

Press F5 in VS Code to launch the Extension Development Host for testing.

Set VSCODE_TEST_VERSION=1.85.0 to run the desktop smoke test against the minimum supported version, or VSCODE_TEST_EXECUTABLE to use a specific installed VS Code executable. The runner uses isolated settings and extension directories. Set GHOSTTY_TEST_CHROME=1 to run browser tests with installed Google Chrome instead of Playwright's Chromium.

The browser harness serves the actual webview bundle and CSP on loopback with a simulated host. The desktop smoke test uses real webviews and local shells. Before release, also check native clipboard shortcuts, platform-specific shells, and rendering at different display scale factors.

License

See LICENSE.

Gespenst and Ghostty license notices are copied into media/licenses/ during the build and included in the VSIX. See THIRD_PARTY_NOTICES.md.