A native macOS chat client for Hermes Agent by Nous Research.
Hermes Agent ships as a CLI — powerful, but not something you want to live in all day. This app wraps hermes acp in a native three-pane workbench: sessions on the left, chat in the middle, tool inspector on the right. Everything streams in real time. No Electron, no web wrapper — pure SwiftUI.
Built with SwiftUI. All agent work — model calls, tool execution, memory, skills, sessions — runs inside hermes acp. This app speaks the Agent Client Protocol (ACP) over stdio to that subprocess and renders its events into a native macOS window.
- Stream chat — agent responses render token by token as they arrive
- Markdown rendering — code blocks, bold, italic, inline code
- Session management — create, switch, rename, delete sessions; history persists across restarts
- Tool call inspector — see every tool call and its result in real time
- Permission prompts — ACP permission requests surface as native approval sheets
- Model switching — change models mid-session via the inspector picker
- Collapsible inspector — toggle the right panel to focus on the conversation
| Requirement | Version |
|---|---|
| macOS | 14 (Sonoma) or later |
| Xcode command-line tools | 15 or later |
| Hermes Agent | latest |
Follow the Hermes quickstart to install hermes and complete initial setup (API key, model, etc.).
Verify it works:
hermes --versiongit clone https://github.com/wislonl/hermes-agent-macos.git
cd hermes-agent-macos./scripts/run-macos-app.shThis compiles the app, creates apps/macos/.build/HermesAgent.app, and opens it automatically.
Alternatively you can run directly without creating a .app bundle:
swift run --package-path apps/macos HermesAgentThe app searches for the hermes executable in this order:
$HERMES_EXECUTABLEenvironment variable (set this for a custom path)~/.local/bin/hermes/usr/local/bin/hermes/opt/homebrew/bin/hermescommand -v hermesvia your login shell (zsh)
If the app shows "Hermes not found" on launch, set the environment variable before running:
HERMES_EXECUTABLE=/path/to/hermes ./scripts/run-macos-app.sh| Action | How |
|---|---|
| Send message | Press Return |
| New line in input | Press Shift + Return |
| New session | Click ⎋ icon in the sidebar, or ⌘N |
| Switch session | Click any session in the sidebar |
| Rename session | Click ⋯ → Rename |
| Delete session | Click ⋯ → Delete (asks for confirmation) |
| Toggle inspector | Click the sidebar.trailing button in the toolbar |
| Change model | Use the picker at the top of the inspector panel |
"Hermes not found" on launch
hermes is not in any of the searched paths. Set HERMES_EXECUTABLE to its full path and relaunch.
Messages not sending / input disabled
The connection status dot (bottom of the inspector) is red — hermes failed to start. Check that hermes acp runs without errors in your terminal.
Session history missing after restart
History is read from ~/.hermes/sessions/. Make sure hermes wrote the session file (it only saves sessions that have at least one message).
App can't be opened (Gatekeeper warning)
The binary is unsigned. Right-click HermesAgent.app → Open, then click Open in the dialog. You only need to do this once.
apps/macos/ macOS SwiftUI app (Swift Package)
Sources/HermesAgent/
HermesAgentApp.swift App entry point, menu commands
AppState.swift Observable state, ACP lifecycle
Models.swift UI value types, markdown helpers
Views/
WorkbenchView.swift Three-pane window layout
SidebarView.swift Session list
ConversationView.swift Chat view with markdown rendering
InspectorView.swift Tool calls, model picker, status
ACP/
ACPSchema.swift ACP wire types (JSON-RPC structs)
JsonRpcTransport.swift Newline-delimited JSON-RPC over stdio
ACPClient.swift High-level ACP client
scripts/
run-macos-app.sh Build + bundle + launch script
docs/ Additional documentation
Pull requests are welcome. For larger changes, open an issue first to discuss what you'd like to change.
Apache License 2.0 — see LICENSE.