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

What HermesPet is, and who it is actually for

The README opens with a complaint rather than a feature list: AI should not live in a single chat box. HermesPet answers that by making the AI a resident of the macOS desktop. The notch area becomes a task entry point, the screen edge becomes a control console, and a small desktop pet switches appearance with the active AI mode and signals when a background task finishes. The stated goal is not another chat wrapper but an AI Mission Control.

The audience is narrow and specific. You need a Mac with macOS 14 or later, and you need to run more than one AI workflow. A user with a single ChatGPT tab gains little. Someone juggling an online model, a locally logged-in Claude Code session and a Codex run, while also wanting CPU, memory, temperature, storage and network figures in the same panel, is the intended reader. The README also says the iPhone and Apple Watch companions are still in development and are not part of the macOS DMG, so the cross-device story is a roadmap item, not a shipping feature.

Seven AI nodes behind one control surface

HermesPet does not implement models. It aggregates terminals. The README lists seven node types and how each connects. Cloud covers everyday question answering, writing, summarization and visual understanding, configured in-app with your own API key. Hermes is for OpenAI-compatible gateways, self-hosted models and internal company models, configured with a compatible endpoint and model name. OpenClaw is described as a gateway-style AI platform and multi-model aggregator that must be installed and started separately. Claude Code, Codex, QwenCode and Kimi reuse the login state already present on the machine.

That last group is the interesting design decision. Instead of asking you to paste keys for every terminal, HermesPet detects tools you have already installed and authenticated. The README is explicit that missing terminals do not block basic use: a first-time user only needs to pick one online provider, and the advanced terminals can be unlocked later. The trade-off is that terminal health checks and login-state detection are listed on the roadmap as work still in progress, so detection can be the fragile part of an otherwise self-contained app.

Installing HermesPet from the signed DMG

The README recommends the official DMG and says ordinary users do not need to build from source. Open the Releases page and pick the file matching your chip: `HermesPet-*-AppleSilicon.dmg` for Apple silicon, `HermesPet-*-Intel.dmg` for Intel. The project states that official builds are Developer ID signed and notarized, and that the signing Team ID is `R34KL4X4D9`. Anything offered outside the repository and the website is not an official release.

There is no install command. The README gives a drag-and-drop step instead: open the DMG and move the app into Applications.

# No build step is documented. The README gives this manual flow:
# 1. Download HermesPet-*-AppleSilicon.dmg (or HermesPet-*-Intel.dmg)
# 2. Double-click the DMG
# 3. Drag "Hermes 桌宠" into /Applications
# 4. Launch it from Launchpad or Spotlight

After launch, the first real task is configuration, not conversation. Open settings, choose an online AI provider and enter your own API key. The README notes that HermesPet does not create or resell model accounts. Once a provider responds, the notch entry and the screen-edge panel become usable.

Terminal nodes come later. Install and log in to Claude Code, Codex, QwenCode, Kimi or OpenClaw in your own terminal first, then return to HermesPet and let it re-detect. The README does not document a manual path override for detection, so if a terminal is installed in a non-standard location, expect to troubleshoot it yourself.

What the desktop actually gives you day to day

The interaction model is built around not leaving the current window. Moving the mouse onto the desktop pet expands a sidebar from the screen edge. The near side holds common actions; the far side shows live system diagnostics: CPU, memory, temperature, storage, network throughput and the connection state of each AI node. The README's point is that you should not have to open a full window to answer a question about machine load.

The README documents a set of global shortcuts. `⌘⇧H` shows or hides the chat window, `⌘⇧J` takes a screenshot and attaches it to the current conversation, `⌘⇧V` is push-to-talk, `⌘⇧Space` opens a quick-ask popover, `⌘⇧L` starts continuous voice chat, `⌘⇧N` opens AI notes and `⌘⇧G` opens the knowledge graph. Screenshots can be full screen or a selected region. Files and images can be dragged into the chat or dropped onto the pet at the screen edge.

The part that distinguishes this from a floating chat window is per-conversation isolation. Each conversation binds to its own AI mode, tasks keep running in the background, and completion is announced through the notch and the pet. The README also promises visible execution steps: file reads, commands, tool calls and error states are shown rather than a single thinking indicator. Whether that rendering is as complete as the claim is not something the README demonstrates, and the repository does not contain the app source to check.

The public repository is a website, not the app

This is the limitation that matters most for anyone evaluating the project. The repository description advertises Swift 6, SwiftUI and macOS 14+, but the top-level entries are `client/`, `server/`, `shared/`, `drizzle/`, `drizzle.config.json`, `vite.config.ts` and `tsconfig.json`. The `package.json` is named `hermes-pet-site`, runs Vite and esbuild, and depends on Express, Drizzle ORM and the Radix UI component set. That is a TypeScript web stack. It is the marketing site and its backend, not the desktop app.

The README confirms the arrangement: the public repository is mainly for product introduction, official downloads, release notes and issue reports, and users are told to prefer the signed and notarized DMG. The consequence is that you cannot audit the binary you run, you cannot build it yourself, and you cannot patch it. The repository does carry an MIT licence, but that licence covers the site code in this repository, not the macOS application, whose licensing terms are not stated in the README.

There is a second gap. The README names the Swift version and the macOS floor, but it does not document a minimum RAM figure, a disk footprint, or what happens on first launch if the notarized build is blocked by a corporate policy profile. For a closed-source app that requests screen, microphone and accessibility permissions, that missing detail is not cosmetic.

Privacy boundaries the README states plainly

The privacy section is unusually direct for a product page, and it is worth reading before you configure a provider. Conversations, images and task records are stored first in a local directory on your Mac. When you ask a question, the request goes to the model provider or terminal tool you selected, and each of those has its own privacy policy. API keys and connection settings are stored locally by the Mac client.

The honest paragraph concerns remote access. The README states that remote features are not routed only through iCloud and do not avoid a server entirely: when phone remote features are enabled, the Mac and the companion app use account authentication and an official relay service for external communication. It also says the account, transport and data retention boundaries will be documented further before the official release. Treat that as an open item. If your organisation forbids third-party relays, the phone features are out of scope until those boundaries are published, and the README does not offer a self-hosted relay option.

System permissions are described as triggered per feature and decided by you through macOS dialogs. Screen viewing, microphone and accessibility all fall into that category.

How it compares with terminal-first and menu-bar tools

The closest alternative in spirit is running Claude Code, Codex or QwenCode directly in a terminal window. That approach keeps everything in text, works over SSH, and has no permission model beyond your shell. HermesPet trades that for observation: it reuses the same login state but adds a persistent control surface, execution-step display, system telemetry and desktop notifications. If your work is a single long coding session in one terminal, the terminal is simpler and you lose nothing by skipping HermesPet.

A second comparison is the menu-bar utility category: small macOS apps that sit in the status bar and expose one function, such as a launcher or a system monitor. HermesPet occupies the notch and screen edge instead, and bundles chat, screenshots, voice input, diagnostics and multi-terminal status into one app. That is more surface area to trust and more permissions to grant. The menu-bar route stays auditable and lightweight; HermesPet asks for a signed binary and a set of system permissions in exchange for the aggregated view. Neither is wrong, but the choice is about how many AI sessions you actually run at once.

The README also positions HermesPet against chat wrappers specifically, saying the goal is not another shell around a chat window. The knowledge graph, which turns long conversations into a searchable map of topics, is the feature that most clearly goes beyond a wrapper. The README does not describe the graph's storage format or whether it can be exported.

Maintenance, upgrades and what to check first

The repository is not archived, and the last push was on 2026-09-02, the same day as the v1.5.12 release. The two prior releases, v1.5.11 and v1.5.10, landed on 2026-07-24 and 2026-07-18. That is a steady cadence across the summer, and the README describes an independent developer maintaining the project long term.

Upgrades are handled inside the app: the README states HermesPet has a built-in update check, and that because official builds are signed and notarized, system permissions survive upgrades more reliably than they would with self-built binaries. That is the practical argument for the DMG over a source build, and it is also the reason a fork is not a realistic option here.

Before you install, verify three things. Check the Releases page and confirm you are downloading the DMG for your chip. Confirm the signing Team ID matches `R34KL4X4D9`. Then read the remote-access paragraphs in the README and decide whether the relay service described there is acceptable for the data you plan to send. The roadmap in `todo.md` lists terminal health checks, multi-agent orchestration, scheduled tasks and clearer remote-access documentation as pending work, so those are the areas where behaviour is most likely to change between releases.

Editorial conclusion

Adopt HermesPet if you work on a MacBook running macOS 14 or later and want one place to watch Cloud, Hermes, OpenClaw, Claude Code, Codex, QwenCode and Kimi sessions without leaving the desktop. Skip it if you are on Windows or Linux, if you need the iPhone or Apple Watch companion today, or if you will not accept a closed-source app whose public repository only hosts the website. Before installing, open the Releases page, confirm the DMG is signed with Team ID R34KL4X4D9, and read the remote-access paragraphs in the README, which state that phone features do not travel only through iCloud.

Frequently asked questions

Official sources

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