The macOS terminal for people who live in shells — and AI CLIs.
Real PTY. Ghostty VT semantics. Smooth history that stays out of your way.
Install · Why · What you get · Build · Architecture · Contributing
ProGhostty is a native macOS terminal you can use as a daily driver: fork real shells, speak real VT, split workspaces, and read long Codex / Claude sessions without the viewport fighting you.
It does not reinvent your shell. zsh, fish, prompt, tmux, vim, fzf, htop, Codex, Claude Code — same PTY path you already trust.
Not affiliated with Ghostty. We vendor Ghostty and run
libghostty-vtas the terminal semantics engine. Product UI stays on the right side of that boundary.
Ship builds on every tagged release. Start here:
# or build from source
git clone --recursive https://github.com/freecodetiger/ProGhostty.git
cd ProGhostty
# see Build from source| Signing | Ad-hoc (open-source releases). First launch may need Right-click → Open or Privacy & Security → Open Anyway. |
| Updates | In-app check opens the matching GitHub Release when a new v* ships. |
| Platform | macOS 14+, Apple Silicon & Intel via SwiftPM (release DMG tracks CI). |
Terminals fail in two boring ways:
- Pretty UI, soft VT — a second parser in the app layer slowly disagrees with reality.
- Correct VT, hostile history — you’re halfway through a long AI answer and the view snaps to live tail.
ProGhostty is built so those two failure modes stay rare:
| Pillar | What it means in practice |
|---|---|
| Semantics first | Cursor, scrollback, styles, ANSI — libghostty-vt is the only truth. Swift never re-parses the stream. |
| Architecture that holds | Strict App → Core → PTY → VT → Renderer chain; Core cannot import SwiftUI (CI guard). |
| History that works | Pattern‑2 smooth pixel scroll: browse without freezing new output, return to live without false bottoms. |
| Your shell stays yours | No mandatory plugin takeover, no “managed” dotfiles. Enhancements are opt-in. |
If you want macOS-native chrome on honest terminal plumbing, you’re in the right repo.
- Real PTY panes — independent processes, proper resize, signals, full-screen TUIs.
- Ghostty VT core — battle-tested parse & state, not a hobby ANSI subset.
- Metal-first rendering — direct draw path for smooth scroll; cell-grid / text fallback when needed.
- Workspaces & splits — multi-pane layouts, multiple workspaces, predictable focus.
- Themes that cohere — Default + Soft Dark / Soft Light; title bar and settings follow the terminal palette.
- Path-aware UX — drop paths into the pane; ⌘-click files to reveal in Finder.
- Useful title bar — workspace + focused pane directory; hover for full path.
- Stable long-output reading — scroll history while agents keep printing; no “freeze the world” history mode as the happy path.
- Shift+Enter multi-line where TUIs expect it; Enter still submits.
- Side input (⌘P) — pop a lightweight input while browsing history; type a command or prompt, Enter pastes it into the real session — without jumping your scroll position. Rebindable in Settings.
- Optional task notifications — agent Stop hooks → toast / sound / system notify (off by default, install with consent).
- No second VT truth in Swift
- No default hijack of your shell config
- No feature that only works by scraping terminal text when the VT already knows
ProGhostty ships continuous v0.4.x releases with scroll stability, themes, notifications, and AI-CLI polish already in the box. Open source means the backlog is public and movable — not that the app is a prototype.
Coming next (community-shaped): notarized / wider distribution options, richer theme import, more workspace power tools, contributor-driven fixes.
Track work and ideas: Issues · Releases.
| Tool | Notes |
|---|---|
| macOS 14+ | App target |
| Swift 6.1 | Language mode .v6 |
| Zig 0.15.2 | Vendored libghostty-vt |
| Xcode | App bundle / signing tooling |
| Git submodules | Vendor/ghostty |
git submodule update --init --recursiveA Debug VT library makes parsing pathologically slow. Always use ReleaseFast:
cd Vendor/ghostty
zig build \
--global-cache-dir ../../.zig-cache-global \
-Demit-lib-vt=true \
-Demit-xcframework=false \
-Doptimize=ReleaseFastFull notes: docs/libghostty-vt.md.
swift build
swift test
scripts/check-architecture.shswift build alone does not refresh the .app bundle. For a real launch:
./scripts/build-app-bundle.sh release
open .build/arm64-apple-macosx/release/ProGhostty.appOne pipeline. One owner per concern.
PTY bytes
→ PTYTerminalEngine session lifecycle & I/O
→ GhosttyVTBridge.write
→ libghostty-vt ★ sole terminal state
→ frame / scrollFrame / rows(at:)
→ TerminalRenderFrame immutable snapshot
→ Metal direct | cell-grid | text fallback
| Concern | Owner |
|---|---|
| PTY / sessions | PTYTerminalEngine |
| VT state | libghostty-vt via GhosttyVTBridge |
| Smooth browse | SmoothScrollEngine + browse present |
| Pixels | Metal / cell-grid backends (paint only) |
| Workspaces | PaneWorkspaceController |
Deep dive: docs/architecture/ownership-map.md · agent rules: CLAUDE.md.
Sources/
ProGhosttyApp/ macOS app, settings, windows
ProGhosttyCore/ PTY, VT bridge, renderer, workspace
ProGhosttyGhosttyVT/ C surface for libghostty-vt
ProGhosttyPTY/ forkpty / resize helpers
ProGhosttyPG/ `pg` helper CLI
Vendor/ghostty/ vendored Ghostty (MIT)
Tests/ swift-testing
scripts/ bundle, DMG, architecture guard
Contributions are welcome — from one-line docs to scroll/VT hard problems.
| You care about… | Jump in on… |
|---|---|
| Daily-driver bugs | Repro + PR or detailed issue |
| Scroll / split / resize | Pattern‑2 + pane layout |
| Themes & settings chrome | Cohesive palettes, a11y contrast |
| Docs & onboarding | Screenshots, build tips, translations |
| Tests | Pure value types & scroll resolvers |
swift build && swift test && scripts/check-architecture.sh
# UI / renderer? also:
./scripts/build-app-bundle.sh release # hand-test the .appIn the description: user-visible behavior, layer touched (PTY / VT / renderer / workspace / settings), how you tested.
Commits: Conventional Commits — see docs/git-workflow.md.
- Issues — bugs & ideas
- Releases — DMGs & notes
- ⭐ Star the repo if ProGhostty is your daily terminal — it helps the next person find a VT-honest macOS app.
Download · Star · Report / request
MIT for ProGhostty.
Vendored Ghostty: MIT — Vendor/ghostty/LICENSE.
Native Swift · libghostty-vt · real PTY · made for people who don’t leave the terminal
中文界面 · English docs for the global community