Hermternal

Hermternal is a native macOS client for the Hermes agent gateway. It lets you sign in through a browser, open Hermes chats, and send messages from a SwiftUI and AppKit application.

Scope

Hermternal is a client for an existing Hermes gateway. It does not run a gateway or provide a general chat service. You must have access to a reachable Hermes gateway.

Requirements

• macOS 26 or later.
• A reachable Hermes gateway URL.
• A browser that can complete the gateway sign-in flow.

Install

1. Open the v0.0.4 release.
2. Download Hermternal-0.0.4.zip.
3. Extract the archive.
4. Move Hermternal.app to the Applications folder.
5. Open Hermternal and enter your Hermes gateway URL. Sign-in opens your browser.

The v0.0.4 archive is notarized. macOS Gatekeeper can verify the application before it starts.

Build from source

Build on macOS 26 or later from the repository root:

bash Scripts/build-app.sh

The script builds a debug application by default and writes the bundle to:

build/Hermternal.app

For a release configuration, run:

CONFIG=release bash Scripts/build-app.sh

Current features in v0.0.4

• Native SwiftUI and AppKit macOS application.
• Browser-based native sign-in with PKCE and a local callback.
• Hermes gateway connection over its WebSocket JSON-RPC interface.
• List existing chats, create a chat, resume a chat, send a message, and interrupt a reply.
• Stream assistant replies and show gateway errors in the application.
• Optional local chat-history cache with background prefetch, cache progress, rebuild, and clear controls.
• Markdown text, inline formatting, fenced code blocks, code copying, and text selection.
• System, Light, and Dark appearance modes.
• Adjustable window frost setting and native Appearance and Cache settings tabs.
• Persistent server selection and stored sign-in credentials for the selected gateway.
• Reduce Transparency produces an opaque, legible system fallback across existing glass and material surfaces.
• Chat and message deep links open a chat and target a message.
• Sidebar folders organize chats, drag reorder changes their order, and scheduled runs have their own section.
• Sidebar row actions pin, archive, and rename chats.
• The sidebar shows the selected gateway identity in a gateway pill.
• The performance contract runner is available for release audits.
• The application bundle carries an appearance-aware native macOS app icon.
• The new-chat state is an icon-only mark, with no placeholder copy.
• The sidebar shows one left caret, aligns rows with Schedules, and mirrors its top and bottom fades.
• A cold-launch deep link waits for the application to become ready and the chat list to finish loading before it opens.

Planned work

These items are tracked in Forgejo. The issue descriptions are the source of truth for planned behavior.

Search and navigation

• Chat and message deep links.
• Local chat search with Command-K.
• Core Spotlight indexing.
• Command-Shift-K action mode.
• Command-F find in the current conversation.

Composer and messages

• Voice notes, attachments, and model or reasoning controls.
• iMessage-like chat bubbles.
• Markdown-first composer and message bubbles.

Platform and integration

• Accent color settings.
• Curated Appearance theme gallery.
• Native motion pass.
• Help settings tab.
• App Intents for Siri and Shortcuts.
• Accessibility audit and remediation.
• NavigationSplitView divider decision record.

Infrastructure

• Password sign-in test gateway and client support.
• Deterministic performance and hitch harness.
• Notarized release credentials and key ACL setup.
• Complete history retrieval beyond 500 messages.

Known limitations in v0.0.4

• The native split view uses a hairline divider with a tonal step.
• Attachments, voice input, model controls, and reasoning controls are not implemented.
• Automatic updates are not implemented.

Architecture

The released application is a Swift Package executable target. SwiftUI supplies the views and AppKit supplies macOS application and browser integration.

AppModel is the main-actor coordinator for sign-in, gateway state, chats, messages, and cache state. AuthClient performs the native PKCE flow, receives the loopback callback, exchanges the code for bearer credentials, and requests a WebSocket ticket. CredentialStore stores credentials in an owner-only file keyed by the gateway origin.

GatewayClient is an actor that uses URLSessionWebSocketTask for newline-delimited JSON-RPC calls and gateway events. RestClient loads session history over HTTP. HistoryCache is an actor that stores versioned transcript JSON files under the macOS cache directory. MarkdownMessage parses completed replies into prose and fenced-code segments; streaming text is shown without reparsing the whole message on every delta.

Contributing

Read CONTRIBUTING.md before you open a pull request. It contains the Contributor License Agreement (CLA). By opening a pull request, you agree to the CLA terms described there.

License

Hermternal is licensed under the GNU General Public License, version 3 or later (GPL-3.0-or-later). Forks must remain open under the same terms. Selling a fork or a build is allowed by the license terms. Copyright is held jointly by K Gopal Krishna and Aayushy Swetapragyan.

Maintenance note

This README describes the latest release on main. Update it only as part of a release. Development plans live in Forgejo issues, not in README prose.