HermesPet macOS AI Companion - Setup Guide¶
Source: reason-machines/hermes-skills · 38 installs Category: Hermes Agent Variants / Desktop Integration License: MIT · Platform: macOS · Published: June 2026
A macOS-native desktop companion built on the Hermes Agent framework. Provides persistent visual presence, interaction feedback, and personality to your Hermes agent - turning it from a background process into a visible desktop assistant.
What It Does¶
| Feature | Description |
|---|---|
| Desktop Pet | Animated character lives on your macOS desktop |
| Agent Status | Visual feedback for agent state (idle, working, error) |
| Quick Commands | Click interactions for common Hermes commands |
| Notifications | Desktop alerts for agent task completion |
| Persistence | Survives sleep/wake cycles, always visible |
The companion bridges the gap between a headless agent process and an interactive desktop experience - useful for development, demos, and keeping Hermes visible during long-running tasks.
Prerequisites¶
- macOS 14 Sonoma or later
- Hermes Agent installed and configured
- Node.js 18+ (for npx installation)
- Accessibility permissions granted (System Settings → Privacy → Accessibility)
Installation¶
Via skills.sh (Recommended)¶
npx skills add reason-machines/hermes-skills@hermespet-macos-ai-companion
Manual Clone¶
git clone https://github.com/reason-machines/hermes-skills.git
cd hermes-skills/hermespet-macos-ai-companion
npm install
npm run build
Start the Companion¶
npm start
On first launch, macOS will request Accessibility permission. Grant it for the companion to overlay on the desktop.
Usage with Hermes Agent¶
After starting, the pet appears as a small animated character in the corner of your screen. It changes expression based on:
- Idle: Neutral, occasional animations
- Processing: Focused/working animation when Hermes is executing tasks
- Complete: Success animation when tasks finish
- Error: Alert expression when something fails
Click the pet to access a quick-command menu for common Hermes operations.
# The companion autodetects Hermes via the hermes CLI
hermespet-macos-ai-companion --hermes-profile corpusiq
Configuration¶
// ~/.hermespet/config.json
{
"hermesProfile": "corpusiq",
"position": "bottom-right",
"size": "small",
"animations": true,
"soundEffects": false,
"startOnLogin": true
}
| Option | Values | Default |
|---|---|---|
position |
top-left, top-right, bottom-left, bottom-right | bottom-right |
size |
small, medium, large | small |
animations |
true/false | true |
soundEffects |
true/false | false |
startOnLogin |
true/false | false |
CorpusIQ Use Cases¶
| Use Case | How |
|---|---|
| Agent monitoring | Visual cue when long-running tasks complete |
| Demo/presentation | Desktop-visible agent for showing Hermes to others |
| Development feedback | Instant visual state for debugging agent workflows |
| Always-on awareness | Never forget Hermes is running a background task |
Troubleshooting¶
| Issue | Fix |
|---|---|
| Pet doesn't appear | Grant Accessibility permission in System Settings |
| Pet frozen | Restart with npm restart |
| Hermes not detected | Verify hermes is in PATH; pass --hermes-profile explicitly |
| High CPU usage | Set animations: false in config |
← Skills Catalog | Marketplace →
Part of the Hermes Skills Library. Curated by CorpusIQ - one MCP endpoint, all your business tools. Content remains attributed to original authors and repositories.
Integration with CorpusIQ¶
CorpusIQ is the connector layer that lets AI assistants read the systems a business already runs on - accounting, payments, CRM, email, files and analytics - and answer with the source named. It is read-only by design: it retrieves data and never writes to, or acts in, a connected system, which is what makes it safe to point at live accounts.
This page is part of the CorpusIQ directory, the reference we maintain for the MCP server and agent-skill ecosystem. Run alongside CorpusIQ, a third-party server like this one can be combined with a company's own business data in a single answer.