DEV.to author 0xkoji shared a relatable experience this week: installing Hermes Desktop on macOS only to discover it wasn't what they expected. Originally anticipating a client application for their existing Hermes agent setup, they found something entirely different. The result? A clean four-step uninstallation guide that covers all the bases.

What Is Hermes Desktop Anyway

Hermes Desktop appears to be a standalone gateway application for macOS that runs as a background service via launchd. Based on the uninstall instructions, it installs a binary at ~/.local/bin/hermes, creates configuration in ~/.hermes/, and registers a LaunchAgent called ai.hermes.gateway.plist in ~/Library/LaunchAgents/. Understanding these installation locations is crucial before attempting removal—miss one and you'll find phantom processes haunting your system.

Step 1: Stop the Gateway Service

The first step is gracefully shutting down the Hermes gateway service using its own command. Running hermes gateway stop tells the application to halt operations in a controlled manner rather than forcing termination. This ensures any pending tasks or connections are properly closed before you proceed with harder removal steps.

Step 2: Kill Remaining Processes

Even after graceful shutdown, residual processes may linger. The pkill -f "hermes" command aggressively terminates any running Hermes-related processes by pattern matching. This is your safety net—better to be thorough than leave background services eating resources or causing conflicts when you try reinstalling later.

Step 3: Remove Application Files

Two commands handle file cleanup: rm -f ~/.local/bin/hermes removes the main binary, while rm -rf ~/.hermes wipes the entire configuration directory. The second command uses recursive (-r) and force (-f) flags to delete everything inside .hermes without prompts. Verify these paths exist on your system before running—installation methods may vary.

Step 4: Clean Up System Services

This is where many users drop the ball. Hermes Desktop registers itself with macOS launchd, meaning it could restart on login or after crashes. Three commands handle this properly: unload the LaunchAgent configuration, remove the service from launchctl's registry, and delete the plist file itself. Skipping any of these means Hermes might mysteriously reappear.

Key Takeaways

  • Always research what an application actually does before installing system-wide tools
  • Check ~/.local/bin and ~/Library/LaunchAgents when auditing unfamiliar background services
  • Use pattern matching (pkill -f) as a safety net when hunting down lingering processes
  • launchctl cleanup is often forgotten but critical for truly removing auto-starting apps

The Bottom Line

We've all been there—install something expecting one behavior, getting another. The good news? Complete removal isn't hard once you know where to look. Bookmark this guide if you work with AI agents and gateways regularly; the pattern of binary + config directory + LaunchAgent appears constantly in this space.