HVOS

HVOS is a floating macOS voice and text shell for Hermes Agent. It gives you a fast little pill for typing, push-to-talk, live run activity, and session previews, all backed by the Hermes Agent API server.

It is meant to feel light, direct, and easy to live with on your desktop: hover to type, hold the hotkey to talk, and keep the chat tucked away until you need it.

What It Does

• Talks to a Hermes Agent server through its OpenAI-compatible API surface.
• Supports typed input and push-to-talk voice input.
• Streams tool activity and final responses back into the floating pill.
• Lives as a proper macOS app with a menu bar extra, custom app icon, and packaged fonts.

Hermes Agent Links

• Project: Hermes Agent
• API docs: Hermes API Server
• Release: HVOS 0.1.0

Requirements

• macOS 14 or newer
• Xcode Command Line Tools
• Swift 6 toolchain
• A running Hermes Agent API server if you want live responses
• An ElevenLabs API key if you want live speech-to-text

Quick Demo

• v1_demo.mp4

Quick Start

Option 1: Use the packaged DMG

Download the installer from the GitHub release page or grab the DMG directly:

• HVOS 0.1.0 release
• Direct DMG download

Open the DMG and drag HVOS.app into Applications.

After that:

1. Launch HVOS.app
2. Enter your Hermes endpoint in Settings
3. Add your ElevenLabs STT key if you want voice input
4. Start using the pill

Option 2: Build it yourself

Build a local app bundle:

./scripts/build-macos-app.sh
open ./build/HVOS.app

Run it directly from SwiftPM during development:

swift run

Configuration

HVOS expects Hermes to be available through the API server endpoint described in the official docs.

Typical local endpoint:

http://127.0.0.1:8642/v1

If you are unsure about the exact server setup, start here:

• Hermes Agent project
• Hermes API server docs

Packaging

Build the app bundle

./scripts/build-macos-app.sh

Output:

build/HVOS.app

Build the DMG

./scripts/build-dmg.sh

Output:

build/HVOS-<version>.dmg

The DMG builder:

• builds the release app bundle
• generates a custom DMG background that matches the app style
• lays out HVOS.app on the left
• places an arrow in the middle
• places the Applications shortcut on the right

Bundled Fonts

The Nothing-inspired typography is bundled from:

Packaging/macos/Fonts

Current set:

• Doto
• Space Grotesk
• Space Mono

These are copied into the app bundle during packaging and registered automatically on launch.

Creating a Release

This is the simple release flow:

1. Update the version in Packaging/macos/Info.plist
2. Build and smoke test the app:

./scripts/build-macos-app.sh
open ./build/HVOS.app

3. Build the DMG:

./scripts/build-dmg.sh

4. Open the DMG locally and make sure:

   • the window opens with the custom layout
   • the app icon looks right
   • dragging to Applications works

5. Create your git tag and push it

6. Create a GitHub release

7. Upload the generated DMG as the release asset

That’s it. Casual desktop app, proper release artifact.

Project Layout

Sources/HVOS/App       app lifecycle, windows, menu bar
Sources/HVOS/Core      models, app state, services
Sources/HVOS/UI        SwiftUI views and styling
Packaging/macos        plist, fonts, packaging assets
scripts                build helpers for app and DMG
assets                 repo images used in docs and packaging
icons                  app icon and menu bar icon sources