Hermes Agent Bar

A tiny macOS menu bar app for running Hermes Agent without leaving your desktop.

Hermes Agent Bar, packaged as HermesBar, puts Hermes Agent in your macOS menu bar. Open a focused chat popover, send prompts, switch projects, run diagnostics, and jump back into Terminal when you need the full CLI.

Built for people who live in agents all day and want the fast path: click, ask, ship.

Highlights

• Native macOS menu bar app built with Swift and AppKit.
• Left click opens the chat instantly.
• Right click opens a clean action menu.
• Terminal-style chat UI with a Hermes-like status bar.
• Project picker, clipboard support, file attach flow, output copy/save, and local slash commands.
• Runs hermes doctor from the app for quick diagnostics.
• Opens normal Hermes sessions, continued sessions, and session browser in Terminal.
• Remembers your selected project, font size, and output panel height.

Preview

Requirements

• macOS 13 or newer.
• Xcode Command Line Tools.
• Hermes Agent CLI installed.
• hermes available in one of these locations:
  • ~/.local/bin/hermes
  • /opt/homebrew/bin/hermes
  • /usr/local/bin/hermes
  • your current PATH

Check your setup:

command -v hermes
hermes doctor

Install Apple's command line tools if Swift is missing:

xcode-select --install

Install

Clone the repo:

git clone https://github.com/cerealskill/hermes-agent-bar.git
cd hermes-agent-bar

Build the app bundle:

./scripts/build_app.sh

Try it locally:

open build/HermesBar.app

Install it into /Applications:

./scripts/install_app.sh

Launch it:

open /Applications/HermesBar.app

Update

git pull --ff-only
./scripts/install_app.sh
open /Applications/HermesBar.app

Usage

Left click ⚚ Hermes in the menu bar to open chat.

Right click ⚚ Hermes for actions:

• Open chat
• Show slash commands
• Cancel current run
• Copy, save, or clear output
• Paste from clipboard
• Attach a file
• Choose a project folder
• Run hermes doctor
• Open Hermes in Terminal
• Continue a session in Terminal
• Browse sessions in Terminal
• Open Hermes config
• Adjust text size
• Quit

Keyboard shortcuts inside chat:

Enter        Send prompt
Shift+Enter  New line

Local wrapper commands:

/copy      Copy output
/save      Save output
/paste     Paste clipboard into input
/doctor    Run hermes doctor
/project   Choose a project folder
/clear     Clear local output
/new       Start a new local session view
/reset     Reset local session state

Build from source

The simple Swift build:

swift build -c release

The app bundle build:

./scripts/build_app.sh

The bundle script does four things:

1. Builds HermesBar in release mode.
2. Creates build/HermesBar.app.
3. Generates and validates Info.plist.
4. Signs the app locally with an ad hoc signature.

Validate the bundle manually:

plutil -lint build/HermesBar.app/Contents/Info.plist
codesign --verify --deep --strict build/HermesBar.app

Project layout

Package.swift
Sources/HermesBar/main.swift
scripts/build_app.sh
scripts/install_app.sh
README.md
LICENSE

Troubleshooting

The app cannot find Hermes

Apps launched from Finder do not always inherit your shell environment. Hermes Agent Bar searches common install paths, then falls back to PATH.

Check where Hermes is installed:

command -v hermes
hermes doctor

If your binary lives somewhere else, update hermesCandidates in:

Sources/HermesBar/main.swift

macOS blocks the app

The app is signed locally with an ad hoc signature. If Gatekeeper warns you, open:

System Settings -> Privacy & Security

Then allow the app to open.

Clean reinstall

osascript -e 'tell application "HermesBar" to quit' >/dev/null 2>&1 || true
rm -rf /Applications/HermesBar.app
./scripts/install_app.sh
open /Applications/HermesBar.app

Development

Run a release build:

swift build -c release

Build the .app bundle:

./scripts/build_app.sh

Install locally:

./scripts/install_app.sh

License

MIT