[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1167":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":19,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":22,"topics":23,"createdAt":10,"pushedAt":10,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":16,"starSnapshotCount":16,"syncStatus":14,"lastSyncTime":27,"discoverSource":28},1167,"hermes-swift-mac","hermes-webui\u002Fhermes-swift-mac","hermes-webui","The best way to run Hermes on your Mac!","",null,"Swift",384,18,2,7,0,12,38,50.64,false,"main",true,[],"2026-06-12 04:00:08","# Hermes Agent for macOS\n\nA native macOS desktop app for [Hermes Web UI](https:\u002F\u002Fgithub.com\u002Fnesquena\u002Fhermes-webui). Built with Swift and WKWebView — no Electron, no dependencies beyond Xcode Command Line Tools. Created by [@redsparklabs](https:\u002F\u002Fgithub.com\u002Fredsparklabs)\n\n\u003Cimg width=\"1470\" height=\"922\" alt=\"Hermes Agent screenshot\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F8e704e62-c736-4827-ba50-c41a21d9922f\" \u002F>\n\n---\n\n## What you need\n\nHermes Agent is a native window for [Hermes Web UI](https:\u002F\u002Fgithub.com\u002Fnesquena\u002Fhermes-webui). The app itself is just a wrapper — it needs Hermes Web UI running somewhere to be useful. Without it you'll see a connection error on launch.\n\n**Required:** Hermes Web UI running on your Mac or a remote server.\n**Optional for remote servers:** SSH key authentication configured for that server.\n**macOS:** 12 (Monterey) or later.\n\n---\n\n## Setup\n\nPick the path that matches where you're starting from.\n\n### Path 1 — New to Hermes: install everything locally\n\nFirst, get Hermes Web UI running on your Mac:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fnesquena\u002Fhermes-webui.git ~\u002Fhermes-webui-public\ncd ~\u002Fhermes-webui-public\nbash start.sh\n```\n\nThis starts the Hermes server at `http:\u002F\u002Flocalhost:8787`. Follow the [Hermes Web UI README](https:\u002F\u002Fgithub.com\u002Fnesquena\u002Fhermes-webui#readme) to configure your API keys during first-run onboarding.\n\nThen install Hermes Agent:\n\n1. Download the latest `Hermes-Agent-vX.X.X.dmg` from [Releases](https:\u002F\u002Fgithub.com\u002Fhermes-webui\u002Fhermes-swift-mac\u002Freleases)\n2. Open the DMG and drag **Hermes Agent** to your Applications folder\n3. Launch the app — it connects to `http:\u002F\u002Flocalhost:8787` by default, which is exactly where you just started Hermes Web UI\n\nNo configuration needed. It works out of the box.\n\n---\n\n### Path 2 — Already have Hermes Web UI running locally\n\nIf Hermes Web UI is already running on your Mac:\n\n1. Download the latest DMG from [Releases](https:\u002F\u002Fgithub.com\u002Fhermes-webui\u002Fhermes-swift-mac\u002Freleases)\n2. Drag **Hermes Agent** to Applications and launch it\n\nThe default Target URL is `http:\u002F\u002Flocalhost:8787`. If you run Hermes on a different port, open **Preferences** (⌘,), update the Target URL, and click **Save & Reconnect**.\n\nYou can verify the connection before saving with the **Test Connection** button.\n\n---\n\n### Path 3 — Hermes Web UI on a remote server\n\nIf Hermes Web UI runs on a server you access via SSH:\n\n**Before you start:** make sure SSH key authentication is working for that server — `ssh user@your-server` should connect without a password prompt.\n\n1. Download the latest DMG from [Releases](https:\u002F\u002Fgithub.com\u002Fhermes-webui\u002Fhermes-swift-mac\u002Freleases)\n2. Drag **Hermes Agent** to Applications and launch it\n3. Open **Preferences** (⌘,)\n4. Set **Connection Mode** to **SSH Tunnel**\n5. Fill in:\n   - **Username** — your SSH username on the remote server\n   - **Host** — the server's hostname or IP address\n   - **Local Port** — port on your Mac (default: 8787)\n   - **Remote Port** — port where Hermes Web UI runs on the server (default: 8787)\n6. Click **Test Connection** to verify, then **Save & Reconnect**\n\nThe app opens an SSH tunnel on launch, monitors it, and tears it down cleanly on quit. The status bar at the bottom of the window shows tunnel state and a one-click Reconnect button if the connection drops.\n\n---\n\n## Install options\n\n### Download the DMG (recommended)\n\nGo to [Releases](https:\u002F\u002Fgithub.com\u002Fhermes-webui\u002Fhermes-swift-mac\u002Freleases), download the latest DMG, open it, and drag Hermes Agent to your Applications folder. The app is signed with a Developer ID certificate and notarized by Apple — no Gatekeeper warning.\n\n### Build from source\n\nRequires Xcode Command Line Tools:\n\n```bash\nxcode-select --install   # if not already installed\n\ngit clone https:\u002F\u002Fgithub.com\u002Fhermes-webui\u002Fhermes-swift-mac.git\ncd hermes-swift-mac\n.\u002Fbuild.sh\n```\n\nThis compiles the app, bundles it with the icon, and installs it to `\u002FApplications\u002FHermes Agent.app`.\n\n---\n\n## Features\n\n- Native macOS app — Dock icon, standard menu bar, works like any Mac app\n- Loads Hermes Web UI in a WKWebView window (no browser needed, no Electron)\n- Direct mode for local Hermes instances, SSH tunnel mode for remote servers\n- Clipboard integration — paste text and images (⌘V) directly into the chat\n- File upload via the paperclip button\n- Preferences window (⌘,) with Test Connection button to verify before saving\n- Status bar showing live tunnel state (SSH mode) with one-click reconnect\n- macOS notifications when an AI response finishes while the window is in the background\n- Voice input — microphone permission requested on first use\n- External links open in Safari, not inside the app\n- Auto-update via Sparkle — checks for new versions on launch, or use app menu → Check for Updates…\n- Signed and notarized — no Gatekeeper warning on first launch\n\n---\n\n## Configuration\n\nOpen **Preferences** (⌘,):\n\n| Setting | Description |\n|---------|-------------|\n| **Connection Mode** | Direct (local) or SSH Tunnel |\n| **Target URL** | URL to load (default: `http:\u002F\u002Flocalhost:8787`) |\n| **Username** | SSH username (SSH mode only) |\n| **Host** | SSH server hostname or IP (SSH mode only) |\n| **Local Port** | Port on your Mac for the tunnel (SSH mode only) |\n| **Remote Port** | Port where Hermes Web UI listens on the server (SSH mode only) |\n\nSettings persist across launches.\n\n---\n\n## Keyboard shortcuts\n\n| Shortcut | Action |\n|----------|--------|\n| ⌘, | Open Preferences |\n| ⌘R | Reload the WebUI page |\n| ⌘W | Hide window (app keeps running in Dock) |\n| ⌘⇧H | Bring Hermes forward from any app (global) |\n| ⌘+ \u002F ⌘− | Zoom in \u002F zoom out |\n| ⌘0 | Reset zoom to actual size |\n\nThe global shortcut ⌘⇧H works system-wide — press it from any app to snap Hermes back to the front.\n\n---\n\n## SSH security\n\n- `StrictHostKeyChecking=accept-new` — on the first connection to a new host, the key is added to `~\u002F.ssh\u002Fknown_hosts` automatically. On all later connections, a changed host key is rejected, protecting against MITM attacks after the first connect.\n- `ExitOnForwardFailure=yes` — the tunnel fails immediately if port forwarding can't be established rather than connecting silently with a broken tunnel.\n- SSH key authentication is required — password auth is not supported.\n\n---\n\n## Troubleshooting\n\n**Connection error or blank page on launch**\nHermes Web UI isn't running. If you're using Direct mode, start it:\n```bash\ncd ~\u002Fhermes-webui-public && bash start.sh\n```\nThen open Preferences and click **Save & Reconnect**, or just relaunch the app.\n\n**\"Unreachable\" in Test Connection**\n- Direct mode: Hermes Web UI isn't running on the configured URL. Check the URL and port.\n- SSH mode: Hermes Web UI isn't running on the remote server, or SSH key auth isn't configured. Test with `ssh user@your-server` in Terminal first.\n\n**SSH tunnel shows \"disconnected\" immediately**\n- `ssh user@your-server` should work without a password in Terminal. If it prompts for one, set up SSH key auth first.\n- The remote port must match where Hermes Web UI is actually listening (default: 8787).\n\n**Voice input not working**\nmacOS requires explicit permission. On first launch a system dialog appears — if you denied it:\n1. Open **System Settings → Privacy & Security → Microphone**\n2. Enable **Hermes Agent**\n3. Restart the app\n\n**Gatekeeper blocks the app**\nYou're on a version older than v1.0.4. Download the latest release — v1.0.4 and later open without any warning.\n\n**App icon looks blurry after building from source**\nRun `killall Dock` to refresh the icon cache.\n\n---\n\n## Architecture\n\n```\nSources\u002FHermesAgent\u002F\n├── main.swift                        — Entry point, signal handling\n├── AppDelegate.swift                 — App lifecycle, menu, Sparkle updater\n├── BrowserWindowController.swift     — WKWebView window, clipboard, notifications, error page\n├── TunnelManager.swift               — SSH process management, port probe, monitoring\n├── PreferencesWindowController.swift — Settings UI, test connection\n└── SplashWindowController.swift      — Launch splash screen\n```\n\n| File | Purpose |\n|------|---------|\n| `Package.swift` | Swift Package Manager manifest (macOS 12+, Swift 5.9+) |\n| `build.sh` | Build script — compiles, bundles .app, converts icon, installs to \u002FApplications |\n| `scripts\u002Frelease.sh` | Release helper — pushes main then tag separately to ensure CI fires |\n| `Tests\u002FHermesAgentTests\u002F` | Unit tests — run with `swift test` |\n\n---\n\n## Releasing\n\nTo cut a new signed and notarized release from a clean `main`:\n\n```bash\nscripts\u002Frelease.sh v1.0.9\n```\n\nThe script pushes `main` first, then the tag as a separate `git push`. This matters: if you push a commit and its tag together (e.g. `git push --follow-tags`), GitHub sometimes drops one of the push events and the Build and Release workflow silently doesn't fire. Splitting the pushes avoids that.\n\nIf a tag push doesn't trigger the workflow within two minutes, kick it off manually: **Actions → Build and Release macOS App → Run workflow → enter the tag**.\n\n---\n\n## Credits\n\nBased on the original native macOS app contribution by [@redsparklabs](https:\u002F\u002Fgithub.com\u002Fredsparklabs) in [hermes-webui PR #544](https:\u002F\u002Fgithub.com\u002Fnesquena\u002Fhermes-webui\u002Fpull\u002F544).\n\n## License\n\nSame license as [hermes-webui](https:\u002F\u002Fgithub.com\u002Fnesquena\u002Fhermes-webui).\n","Hermes Agent 是一个专为 macOS 设计的桌面应用程序，旨在提供最佳的 Hermes Web UI 体验。该应用使用 Swift 和 WKWebView 构建，不依赖 Electron 或其他外部库，仅需 Xcode 命令行工具即可运行。其核心功能包括本地或通过 SSH 隧道连接到远程服务器上的 Hermes Web UI，并提供了一个简洁的用户界面来管理这些连接。适用于需要在 Mac 上高效管理和监控 Hermes Web UI 服务的各种场景，无论是本地开发还是远程服务器运维，都能轻松应对。","2026-06-11 02:42:03","CREATED_QUERY"]