herminal

AI-native macOS terminal cho Vietnamese developers chạy Claude Code và
agent CLIs hằng ngày.

Website: https://hoang.tech/herminal/ · Download: latest release · Source: this repo

Status: v1.0.0 release candidate on main; latest public release is
v0.4.2.
See CHANGELOG.
Platform: macOS 14+ Apple Silicon.

🇻🇳 Phiên bản tiếng Việt: README.vi.md

What is herminal

A local-first macOS terminal built around two daily realities the existing
2026 terminals each miss part of:

1. You run Claude Code / Codex / Aider all day and need a glanceable
   view of which agents are alive, idle, or done — without an
   open-a-second-window detour.
2. You write Vietnamese and need Telex / VNI to land correctly the
   first time, in tmux, in vim, every time.

herminal pairs the libghostty
engine (Zig, mature, native performance) with a Swift / AppKit shell that
owns the IME and the chrome. Storage is SQLite for both per-session notes
and saved SSH hosts. No cloud, no telemetry, no account.

Why a new terminal

In 2026 nothing on the market hits all five at once:

See docs/research/ for the full comparison and
scoring rubric the table is derived from.

v1 scope

Built on main; public v1 remains a release candidate:

• Native terminal core via libghostty (Metal renderer, p95 keystroke <5ms)
• Vietnamese IME bridge with automated Tab/preedit regressions; live Telex/VNI release gate pending¹
• Multi-session workspace + vertical/horizontal splits
• Agent dashboard with running / idle / starting discrimination
• Per-session notes (SQLite WAL) with Markdown round-trip
• SSH Connection Manager with one-click spawn
• Premium dark chrome (Raycast/Linear style)
• tmux compatibility verified against vim, less, htop, fzf, lazygit, btop, starship
• Telemetry-free local crash diary
• Developer-ID codesign + notarize pipeline

¹ The implementation and state-transition regressions are green, but the
release-blocking system-input-source matrix still requires a dated human run.
See issue #2.

Deferred to post-MVP — see CHANGELOG.md "Known
limitations": agent↔pane mapping, recursive split trees, drag-to-resize
dividers, light theme, group/search in SSH manager.

Install

Homebrew (recommended)

brew install --cask hoangperry/herminal/herminal

brew upgrade --cask herminal keeps it current. Public artifacts must be
Developer-ID signed, notarized, and stapled so Gatekeeper can validate them;
macOS may still show its standard first-open confirmation.

Direct download

1. Grab herminal-vX.Y.Z.dmg from the
   Releases page.
2. Open the DMG → drag herminal.app into /Applications.
3. Launch. Verify the publisher in the standard macOS first-open confirmation.

From source

git clone --recurse-submodules https://github.com/hoangperry/herminal
cd herminal
Scripts/bootstrap.sh           # builds libghostty xcframework (~5-15 min cold)
Scripts/make-app-bundle.sh     # assembles .app with ad-hoc signature
open .build/herminal.app

Prereqs: Xcode 26+, Swift 6.2+, Zig 0.15.2+
(for libghostty), clang for the kernel-probe binaries used by the
integration scripts.

First-run quick tour

• ⌘T / ⌘W — new tab / close current pane (closes tab when last)
• ⌘D / ⌘⇧D — split vertical / horizontal
• ⌘⇧] / ⌘⇧[ — next / previous tab
• ⌘⇧A — toggle agent dashboard
• ⌘⇧S — toggle SSH host manager (mutex with the agent dashboard
  in the left slot)
• ⌘⇧N — toggle the per-session notes panel on the right

Agents are detected by walking herminal's process subtree — start
claude, codex, or aider in any tab and they'll appear in the
dashboard within ~2 seconds with a running / idle / starting
badge tracked via CPU sampling.

Tech stack

Repo layout

herminal/
├── Sources/
│   ├── HerminalCore/         # libghostty C ABI bridge
│   ├── HerminalDB/           # NotesStore + SSHHostsStore
│   ├── HerminalAgent/        # process-subtree + CPU-status detection
│   └── HerminalApp/          # NSApp, WorkspaceView, panels, Diary
├── App/                       # Info.plist + entitlements
├── Tests/                     # 48+ Swift Testing unit tests
├── Scripts/                   # bootstrap, bundle, verify-*, dogfood, sign, release
├── Vendor/libghostty/         # git submodule (Ghostty v1.3.1)
└── docs/
    ├── research/             # market scan + scoring
    ├── define/herminal.prd.md # source-of-truth PRD
    ├── backlog/              # monthly task lists + retrospectives
    ├── QA/                   # IME checklist, dogfood checklist + journal
    └── launch/               # press kit + tweet/LinkedIn drafts

Contributing

Read CONTRIBUTING.md first — the project is
opinionated about what's in scope. Bug reports go through the
bug template which prompts for
the diary excerpt; security issues go to
SECURITY.md.

Documentation

Made with 🐈 by Yuuhou Meow team in Việt Nam.