Pratyush Kumar

I Gave an AI Agent Permanent Residence on My Mac

9 min read
  • AI
  • Agents

I Gave an AI Agent Permanent Residence on My Mac: My Hermes Agent Setup

A hands-on walkthrough of installing, configuring, and living with Hermes Agent — the open-source agent framework from Nous Research.

First, what even is Hermes?

If you've used Claude Code, Codex, or OpenClaw, you know the genre: a terminal-native agent that reads your files, runs your shell, and gets real work done with tool calls. Hermes Agent is the open-source entry in that category — and the reason I picked it over the alternatives is what it does after the coding session ends:

  • It remembers. Persistent memory carries facts about you, your environment, and lessons learned across sessions. I don't re-explain my setup every morning.
  • It learns. Anything I teach it once — a workflow, a pitfall, a correction — gets saved as a skill that reloads automatically next time that kind of task comes up.
  • It's everywhere I am. The same agent core runs in the terminal, a desktop app, and a gateway that connects it to messaging platforms. For me, that meant WhatsApp.
  • It's provider-agnostic. It talks to OpenRouter, Anthropic, OpenAI, Google, local models, and 20+ others. You're not locked into one vendor's subscription.

This post is the walkthrough of how I actually set it up on macOS — install, model config, the WhatsApp gateway, cron automation, and skills — with the commands I ran.

Installation

The whole install is one line. The shell script bootstraps the package manager, Python, dependencies, and the launcher:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Then the interactive setup wizard walks you through picking a model and provider:

hermes setup
hermes model      # pick model + provider
hermes doctor     # health check — catches missing deps and bad config

hermes doctor is worth a mention: it's the "did I break anything?" command I run after every config change. Five minutes from curl to a working agent chat in the terminal.

Model configuration

Hermes stores settings in ~/.hermes/config.yaml and secrets in ~/.hermes/.env — a separation I appreciate, because it means I can share or version my config without leaking API keys.

I route through OpenRouter so I can swap models without touching anything else:

model:
  default: z-ai/glm-5.3-flash
  provider: openrouter
  base_url: https://openrouter.ai/api/v1
  api_mode: chat_completions

Two config details that turned out to matter more than I expected:

agent:
  max_turns: 150          # how long an agent can grind on one task
  tool_use_enforcement: auto
  parallel_tool_call_guidance: true
  verify_on_stop: false

compression:
  enabled: true           # auto-compress long sessions
  threshold: 0.5

max_turns is the difference between an agent that can carry a multi-step task to completion and one that gives up halfway. And compression keeps long sessions from quietly eating your context window and your token budget.

Everything under auxiliary: (vision, web extraction, compression, title generation, etc.) defaults to provider: auto, which means it inherits your main provider setup. I didn't have to configure a dozen models individually — one OpenRouter key covers everything.

The part that changed my daily routine: WhatsApp

This is the feature that sold me. Hermes runs a gateway that connects it to messaging platforms — Telegram, Discord, Slack, WhatsApp, iMessage, and more — with full tool access, not just chat. Your agent isn't trapped in a terminal; it's in your pocket.

Setup for WhatsApp was a pairing flow, similar to linking WhatsApp Web:

hermes config set platforms.whatsapp.enabled true
# then pair the device — credentials land in
# ~/.hermes/whatsapp/session/creds.json

A couple of gotchas I hit, so you don't have to:

  1. Incoming messages only arrive while the bridge is connected. If your Mac sleeps or the gateway dies overnight, messages sent during that window are gone — the WhatsApp protocol doesn't backfill chat history. There is no store of past messages anywhere on disk. Plan your automations around "while running," not "catch up later."
  2. Voice notes arrive as .ogg files with no transcription. I fixed this with a small pipeline: convert with ffmpeg to 16 kHz mono WAV, base64-encode, and send as input_audio to a multimodal model. It works, but it's the kind of rough edge you should expect from self-hosting your own agent stack.

The payoff is real: I message my Mac from my phone — "add this to my read list," "what's on my calendar," "summarize this article" — and it acts with the same tools it has in the terminal.

Scheduled work: cron without a cron file

Hermes has built-in scheduled jobs. Two of mine:

twitter ML Discussion — daily at 09:00
  Summarize important posts from X in the last 20 hours about AI/LLM/
  LRM/Data Science/AI Engineering, then produce a digest.

AMZN 1-week tracker — daily at 21:00
  Track Amazon's share price for a one-week tracking engagement,
  running daily until the engagement ends.

Every morning I get an AI-digested briefing of what happened in ML Twitter overnight, assembled by the agent with web access — no feed, no scrolling. The tracker is the other pattern worth stealing: instead of a one-off question ("what's AMZN at?"), you give the agent a standing engagement and it reports daily.

Skills: the agent that learns your workflows

This is Hermes's most underrated feature. When the agent figures out how to do something non-obvious — say, the ffmpeg-plus-multimodal-model voice note pipeline above — it can save that procedure as a skill, which loads into context automatically whenever a matching task appears.

My skills directory now covers twenty categories: Apple (Notes, Reminders, FindMy, iMessage), autonomous AI agents, creative, data science, email, finance, GitHub, media, MLOps, note-taking (Obsidian), productivity, research, smart home, social media, software development, web, WhatsApp messaging, and more.

The ones I lean on hardest:

  • apple — Notes and Reminders from natural language ("remind me to…", "add this to Notes").
  • obsidian — my Obsidian vault is wired in; "add to read list" literally appends a checkbox to the right note.
  • social-media — posting to X, verified end-to-end before the agent reports success.
  • github — PRs, issues, and reviews through the gh CLI, already authenticated.

The compounding effect is the point: month one, you're teaching it your conventions. Month two, it already knows them.

Living with it: the desktop app

While the terminal is where I do serious work, the desktop app (hermes desktop) is where Hermes lives day to day — streaming chat, a session list, drag-and-drop files, native notifications, and a ⌘K command palette. Sessions persist on disk, so I can close the app, come back tomorrow, and resume exactly where we left off.

Lessons learned

  1. Secrets discipline pays off immediately. .env for keys, config.yaml for settings. When I later shared my config, redacting was trivial.
  2. Messaging integrations change how you use an agent. Terminal agents get used when you sit down to work. A WhatsApp-connected agent gets used at the moment you think of the task — which is a different, and arguably better, capture model.
  3. Cron prompts are prompts, not schedules. A good scheduled job has a well-specified prompt ("summarize posts from the last 20 hours about X, then format Y") — the quality of your 9 AM digest is entirely a function of how you wrote that prompt.
  4. Self-hosted integrations have rough edges. Voice-note transcription, expired tokens, API quirks — expect to write small glue scripts. The flip side is that once you fix something, the agent remembers the fix.
  5. Run hermes doctor after config changes. Cheap insurance against a typo silently breaking your gateway.

Should you do this?

If you want an agent that's a tool you use, any of the big-name coding agents will do. If you want an agent that's a resident — one that remembers you, learns your workflows, messages you back, and runs your morning briefing while you sleep — that's the niche Hermes fills, and the setup cost is an afternoon.

Everything here is open source: github.com/NousResearch/hermes-agent, with docs at hermes-agent.nousresearch.com/docs.