HermesPet: a macOS AI companion that lives in the MacBook notch

What HermesPet is, and the problem it addresses

Most desktop AI clients are chat windows. You switch to them, type, wait, and switch back. HermesPet takes the opposite position: the README argues that AI should be part of the desktop surface, with a task entry point under the MacBook notch and an operation panel that expands from the screen edge when the cursor touches the pet. The stated goal is not another chat wrapper but what the project calls an AI Mission Control.

The audience is narrower than "everyone who uses AI". It is macOS 14 or later, Apple silicon or Intel, and it assumes you are comfortable supplying an API key for an online provider or that you already have a terminal agent installed and logged in. The README is explicit that uninstalled terminals do not block basic use: a first-time user only needs to pick one online AI provider, and the advanced terminals can be unlocked later.

Seven AI node types behind one control surface

The mechanism that matters here is the node table. HermesPet lists seven connection types. Cloud covers everyday question answering, writing, summarization and vision, configured in-app with your own API key. Hermes is for OpenAI-compatible gateways, self-hosted models or internal company models, configured with a compatible endpoint and model name. OpenClaw is a gateway-style platform reached by installing and starting OpenClaw itself. Claude Code, Codex, QwenCode and Kimi are reused through the login state already present on your machine rather than through new credentials.

That last group is the interesting design choice. Instead of reimplementing tool calling, HermesPet attaches to terminal agents that already have file access and command execution, and surfaces their connection state, execution steps and errors in one place. The trade-off is that it inherits whatever those tools require: the README says you install and log in to each tool in a terminal first, then return to HermesPet and re-detect. There is no bundled substitute for a missing CLI.

Installing HermesPet from the signed DMG

The README recommends the official DMG over a source build, and it does not publish command line installation steps. What it gives is a file naming convention and a drag-and-drop procedure. Open the releases page, pick the file matching your chip, mount the image and drag the app into Applications. The project states the DMG carries Developer ID signing and Apple notarization, so permission grants survive upgrades more predictably. The README also says ordinary users do not need to build from source.

# Releases page: https://github.com/basionwang-bot/HermesPet/releases/latest
# Apple M series chips: HermesPet-*-AppleSilicon.dmg
# Intel chips:         HermesPet-*-Intel.dmg

Once mounted, the README describes dragging the app into the Applications folder, then launching it from Launchpad or Spotlight. On first run you choose an AI provider in settings and enter your own configuration. Verification is done by Team ID: the README states official builds are signed with R34KL4X4D9, and packages obtained outside the repository and the official site are not official releases.

For the terminal nodes, the sequence is the reverse of what you might expect. Install and log in to Claude Code, Codex, QwenCode, Kimi or OpenClaw in your terminal first, then return to HermesPet and trigger a re-detection. The README does not document a rollback path if a detection fails after an upgrade, and it does not list which versions of those external tools are supported.

The screen edge, the shortcuts, and what runs in the background

Touching the pet with the cursor expands a sidebar from the screen edge. Near-side controls are the common actions; the far side shows live diagnostics for CPU, memory, temperature, storage, network throughput and AI node status, without opening a full window. The README lists seven global shortcuts, including Command Shift H to show or hide chat, Command Shift J to screenshot and attach to the current conversation, Command Shift V for push-to-talk, and Command Shift G for the knowledge graph.

Multiple conversations can run at once, each bound to its own AI mode, with completion signalled through the dynamic island area and the pet. The README claims execution steps, file reads, commands, tool calls and error states are shown rather than a single spinner. Long-term conversation history is described as staying in a local directory on the Mac, searchable by keyword, topic and importance. I would treat the knowledge graph as the least verifiable feature from the README alone: it is shown in screenshots with a one-line description, and no retrieval mechanism or storage format is documented.

Where HermesPet is the wrong tool

The hardest boundary is platform. This is macOS 14 and later only, with separate Apple silicon and Intel builds. There is no Windows or Linux path in the README, and the repository layout reinforces that: the public tree is a TypeScript and Vite site with an Express server, Drizzle config and a client directory, which is the marketing and download site, not the app. The Swift 6 and SwiftUI application itself is distributed as a binary through releases, so if your requirement is to read the full source of the app you run, this project does not satisfy it.

The second boundary is the companion story. The README states plainly that the iPhone and Apple Watch apps are still under development and are not included in the macOS DMG, and that the official way to obtain them will be announced separately at release. Anyone evaluating HermesPet for remote control of a Mac today is evaluating something that does not ship yet.

The third is trust surface. The privacy section says desktop data is stored locally first, but requests go to whichever provider or terminal you configured, and that remote phone features use account authentication and an official relay service over the public internet. The README concedes the remote path is not iCloud-only and says the account, transport and retention boundaries will be documented further before release. That is an honest statement, and also a reason to wait if the remote path is your main use case.

How it differs from a plain menu bar chat client

A conventional menu bar AI client owns the whole interaction: it holds your key, sends the request, renders the answer. HermesPet is closer to an observability layer over several backends. The difference shows up in what you can see. A menu bar client shows you a response. HermesPet's stated aim is to show connection state, execution steps, system load and task progress alongside the answer, with the Mac doing the execution and a phone acting as a viewer and approval surface.

That approach costs you setup. Each terminal node must be installed and authenticated outside the app, and each online provider needs its own key. A single-provider menu bar client is faster to first answer. HermesPet is worth the extra steps only if you actually run more than one backend, or if you want the system telemetry and the screenshot, voice and drag-and-drop entry points in the same place. If you use one model and one chat window, the node table is overhead.

Maintenance, licensing and what to check before adopting

The last push to the repository was on 2026-09-02, and release v1.5.12 is dated the same day, following v1.5.11 on 2026-07-24 and v1.5.10 on 2026-07-18. Those dates describe a project that ships, but the public repository is not where the app is built. Its package.json names the package hermes-pet-site, declares version 1.0.0 and carries an MIT license field, which covers the site code in this tree rather than the distributed application. The repository does not state a licence for the macOS binary, so do not assume the MIT field applies to the app you install. That is a question for the author, not a conclusion you can draw from the file.

Upgrade cost is low by design: the README says the app has a built-in update check and that signed, notarized releases keep system permissions stable across upgrades, so you reinstall a DMG rather than rebuild. The ongoing cost sits in the external dependencies. Every terminal node you enable can change its own login behaviour or command surface, and the README's roadmap puts more reliable terminal health checks and login-state detection near the top of the list, which suggests that detection is not yet fully settled.

Editorial conclusion

HermesPet fits Mac users who want AI next to the menu bar instead of in a browser tab, and who are willing to configure their own API keys or already have Claude Code, Codex, QwenCode or Kimi logged in locally. Skip it if you need Windows or Linux support, if you want a fully open source build you can audit, or if you expect the iPhone and Apple Watch pieces to work today, since the README states they remain in development and are not part of the macOS DMG. Before installing, check the Team ID R34KL4X4D9 signature on the release you download, and read the README section on data and privacy boundaries, which says remote features do use account authentication and an official relay service rather than staying entirely on iCloud.

Frequently asked questions

Official sources

1. basionwang-bot/HermesPet on GitHub
2. Issues
3. Project website
4. README
5. Releases