pi-ghostty-web

Pi extension providing web-based terminal access via ghostty-web

Packages

Package details

extension

Install pi-ghostty-web from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-ghostty-web
Package
pi-ghostty-web
Version
0.1.0
Published
Jul 13, 2026
Downloads
124/mo · 124/wk
Author
picassio
License
MIT
Types
extension
Size
54.6 KB
Dependencies
3 dependencies · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-ghostty-web

A pi extension that provides web-based terminal access using ghostty-web — Ghostty's battle-tested VT100 parser compiled to WASM.

Open a browser tab (or your phone) and get a full terminal session in pi's working directory.

Installation

pi install npm:pi-ghostty-web

Or from git:

pi install git:github.com/picassio/pi-ghostty-web

Usage

Inside a pi session:

/web            Start the web terminal (default port 7681)
/web 8080       Start on a specific port
/web stop       Stop the server

The status bar shows the LAN URL so you can connect from your phone.

Features

Terminal

  • Full terminal emulator in the browser via ghostty-web (WASM)
  • Nerd Font support (JetBrains Mono NF) for zsh themes like Powerlevel10k
  • Each browser tab gets its own shell session in pi's CWD
  • Clean environment — tmux/screen vars are stripped so you can start tmux inside

Session Persistence

  • PTY sessions survive WebSocket disconnects (mobile tab backgrounding, network drops)
  • 100KB replay buffer restores terminal state on reconnect
  • Automatic reconnect with session reattachment — no "connection lost" interruptions
  • 5-minute grace period before orphaned PTYs are killed

Mobile

  • Touch scrolling with three modes:
    • Mouse tracking on (tmux set -g mouse on): SGR wheel events
    • Alternate screen (tmux copy mode, vim, less): arrow keys
    • Normal shell: scrollback buffer scroll
  • On-screen keyboard toolbar with:
    • Special keys: Esc, Tab, Shift+Tab, arrows (◀▼▲▶), PgUp/PgDn, Home/End, Alt+Enter
    • Sticky modifiers: Ctrl, Alt, Shift (tap to activate, double-tap to lock)
    • Modifier + key combos with xterm-style encoding (e.g. Ctrl+◀ = word-left)
  • Text selection:
    • Long-press (500ms) to select word, drag to extend character-by-character
    • Double-tap to select word
    • Floating Copy/Paste/All bubble
  • Virtual keyboard hides when scrolling, shows on tap
  • Viewport resizes when keyboard opens (no content hidden behind keyboard)

tmux Integration

  • tmux button in the top bar opens a control panel with:
    • Windows: New, Prev, Next, Rename
    • Panes: H-Split, V-Split, Cycle, Zoom, Kill
    • Session: List, Scroll (copy mode), Detach

Server

  • Binds to 0.0.0.0 — accessible from other devices on the LAN
  • LAN IP shown in status bar and startup notification
  • Port auto-increment if the requested port is in use
  • WebSocket heartbeat (ping/pong every 20s) cleans up stale connections
  • Static assets cached in memory (ghostty-web JS/WASM served from RAM)
  • Cache-Control headers for browser-side caching

How It Works

┌──────────────┐     ┌───────────────────────────┐     ┌──────────────┐
│  Pi TUI      │     │  Pi Process               │     │  Browser     │
│  (terminal)  │     │                           │     │  (phone/     │
│              │     │  pi-ghostty-web extension  │     │   laptop)    │
└──────────────┘     │    ↳ HTTP + WS server     │◄───►│              │
                     │    ↳ PTY sessions          │     │  ghostty-web │
                     └───────────────────────────┘     │  terminal    │
                                                       └──────────────┘

The extension starts an HTTP + WebSocket server inside the Pi process. The browser loads ghostty-web (WASM terminal emulator) and connects via WebSocket. Each connection is bridged to a real PTY running your shell.

Requirements

License

MIT