[Bug]: Full uninstall leaves Hermes data, Desktop state, LaunchAgents, and application files behind on macOS

[anthonydigrazia]

Bug Description

Running a full Hermes uninstall on macOS does not remove all Hermes-created files and state.

After the uninstall reported that Hermes data had been removed, substantial Hermes-related files and directories still remained across the home directory and macOS Library folders.

These leftovers affected the next installation. Hermes continued to exhibit provider and performance problems until all remaining Hermes files were manually removed.

After a genuinely clean reinstall, performance returned to normal.

Steps to Reproduce

1. Install and use Hermes Desktop on macOS.
2. Run the full uninstall option.
3. Allow the uninstall process to complete.
4. Search for remaining Hermes files:
5. find "$HOME/Library" "$HOME/.local" "$HOME/.config" "$HOME/.cache" \
6. -maxdepth 3 -iname 'hermes' 2>/dev/null
7. Check whether ~/.hermes, LaunchAgents, Desktop state, caches, preferences, logs, and application files remain.
8. Reinstall Hermes.
9. Observe that previous state or degraded behavior may persist.

Expected Behavior

A full uninstall should either:

1. Remove all Hermes-created files, application state, background services, and configuration, or
2. Create a clearly labeled backup of user data before removal and explicitly inform the user which files were preserved.

If ~/.hermes is intentionally preserved, the user should be told that it contains profiles, provider configuration, sessions, memory, skills, and other state that may affect a future reinstall.

A full uninstall should result in a genuinely clean reinstall experience.

Actual Behavior

The full uninstall reported successful removal, but Hermes-related files remained in multiple locations.

The remaining items included or potentially included:

~/.hermes
~/.local/share/hermes
~/.local/bin/hermes
~/.cache/hermes
~/.config/hermes

~/Library/Application Support/Hermes
~/Library/Caches/Hermes
~/Library/Caches/com.nousresearch.hermes
~/Library/Caches/hermes-setup
~/Library/Caches/com.nousresearch.hermes.setup

~/Library/Logs/Hermes

~/Library/Preferences/com.nousresearch.hermes.plist

~/Library/WebKit/com.nousresearch.hermes
~/Library/WebKit/hermes-setup
~/Library/WebKit/com.nousresearch.hermes.setup

~/Library/HTTPStorages/com.nousresearch.hermes

~/Library/Saved Application State/com.nousresearch.hermes.savedState

~/Library/LaunchAgents/ai.hermes.gateway*.plist
~/Library/LaunchAgents/io.nousresearch.hermes-agent.gateway*.plist

/Applications/Hermes.app

Hermes-related gateway processes and LaunchAgents also had to be stopped or unloaded manually.

The following kinds of cleanup were required:

pkill -x Hermes 2>/dev/null || true
pkill -f hermes-agent 2>/dev/null || true

launchctl bootout "gui/$(id -u)/ai.hermes.gateway" 2>/dev/null || true
launchctl bootout "gui/$(id -u)/io.nousresearch.hermes-agent.gateway" 2>/dev/null || true

The remaining files then had to be manually deleted before reinstalling.

Affected Component

Other

Messaging Platform (if gateway-related)

No response

Debug Report

None.  as I didnt know if what I did would solve, and I deleted all things Hermes!

Operating System

macOS 26.5.2

Python Version

3.11.9

Hermes Version

0.18.2

Additional Logs / Traceback (optional)

Root Cause Analysis (optional)

No response

Proposed Fix (optional)

For hermes uninstall --full:

Stop all Hermes processes.
Unload all Hermes LaunchAgents.
Remove the Desktop app.
Remove Electron/WebKit caches and state.
Remove preferences, logs, HTTP storage, and saved application state.
Remove or archive ~/.hermes.
Show the user an exact list of preserved and deleted locations.

A safer user-friendly approach would be:

Create a timestamped backup such as:
~/.hermes-backup-YYYYMMDD-HHMMSS
Inform the user that the backup contains profiles, sessions, provider configuration, memory, and skills.
Remove the active ~/.hermes directory so the next install is genuinely clean.
Provide instructions for selectively restoring data without restoring broken configuration.

Are you willing to submit a PR for this?

• I'd like to fix this myself and submit a PR

[GottZ]

This was generated by AI during triage.

Summary

Four PRs are associated with this issue complex, but only #62451 targets #62209’s macOS full-uninstall leftovers: it sweeps XDG/Desktop state, application files, and LaunchAgents. #6137 and #48920 address named-profile retention from #6115, while #34239 addresses deferred cleanup of locked Windows installations.

Related pull requests

• fix: remove named profiles during full uninstall #6137 [closed] unrelated — (+99/-12) — unrelated: Removes named-profile directories during full uninstall, addressing [Bug]: profiles not erased after uninstall, leading to error after reinstall #6115 rather than the macOS Desktop, cache, application, and LaunchAgent leftovers reported in [Bug]: Full uninstall leaves Hermes data, Desktop state, LaunchAgents, and application files behind on macOS #62209. It remains relevant as a closed, superseded implementation attempt; contributor discussion records that commit 79c5a38 implemented its core fix on main.
• fix(uninstall): defer Windows cleanup for live install #34239 unrelated — (+184/-28) — unrelated: Adds deferred Windows removal for locked live installation trees, not cleanup of the macOS paths responsible for [Bug]: Full uninstall leaves Hermes data, Desktop state, LaunchAgents, and application files behind on macOS #62209. The keep_open review on fix(uninstall): defer Windows cleanup for live install #34239 remains relevant to that independent Windows bug and identifies missing coverage for an external project root; it does not make this PR a candidate for consolidating [Bug]: Full uninstall leaves Hermes data, Desktop state, LaunchAgents, and application files behind on macOS #62209.
• fix(cli): remove named profiles during full uninstall #48920 unrelated — (+83/-29) — unrelated: Changes full uninstall to remove named profiles automatically, addressing the [Bug]: profiles not erased after uninstall, leading to error after reinstall #6115 profile-cleanup behavior rather than [Bug]: Full uninstall leaves Hermes data, Desktop state, LaunchAgents, and application files behind on macOS #62209’s macOS Desktop and Library residue. The keep_open review on fix(cli): remove named profiles during full uninstall #48920 identifies a real independent gap plus unsafe test isolation, so it should not be closed merely to consolidate [Bug]: Full uninstall leaves Hermes data, Desktop state, LaunchAgents, and application files behind on macOS #62209.
• fix(uninstall): sweep full uninstall leftovers #62451 best fix — (+242/-1) — partial fix: Directly removes the XDG, macOS Desktop, application, cache, preference, WebKit, saved-state, and LaunchAgent paths reported in [Bug]: Full uninstall leaves Hermes data, Desktop state, LaunchAgents, and application files behind on macOS #62209. Keep it open as the best fix, but address the contributor review before merge: the broad ai.hermes.gateway*.plist sweep can delete live named-profile services, so cleanup must be limited to the selected profile and verified legacy labels with regression coverage preserving non-selected profiles.

Duplicates

#6137 and #48920 substantially overlap on named-profile cleanup for #6115, although #48920 additionally removes the separate interactive opt-in and remains under an independent keep_open review.

Suggested consolidation

Merge #62451 after narrowing its LaunchAgent cleanup and adding the requested named-profile preservation regression test; it is the only listed PR whose diff directly addresses #62209’s reported cause. Do not merge it over the keep_open review as currently written, and do not close #34239 or #48920 as #62209 duplicates because they cover independent Windows and named-profile gaps; #6137 is already closed and superseded by commit 79c5a38.

Complex graph

flowchart LR
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef merged fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    classDef unverified fill:#f3f4f6,stroke:#9ca3af,color:#374151
    classDef best stroke-width:3px,stroke:#b45309
    classDef target stroke-width:3px,stroke:#4338ca
    I6115(["issue #6115 (closed)"])
    I62209(["issue #62209 (open)"])
    P62451["PR #62451 (open)"]
    subgraph Dup6137 ["PRs duplicating each other"]
        P6137["PR #6137 (closed)"]
        P48920["PR #48920 (open)"]
    end
    P62451 -->|best fix| I62209
    P6137 -->|fixes| I6115
    P48920 -->|best fix| I6115
    class I6115 closed
    class I62209 open
    class I62209 target
    class P6137 closed
    class P48920 open
    class P62451 open
    class P48920 best
    class P62451 best
    click I6115 "https://github.com/NousResearch/hermes-agent/issues/6115"
    click I62209 "https://github.com/NousResearch/hermes-agent/issues/62209"
    click P6137 "https://github.com/NousResearch/hermes-agent/pull/6137"
    click P48920 "https://github.com/NousResearch/hermes-agent/pull/48920"
    click P62451 "https://github.com/NousResearch/hermes-agent/pull/62451"

Loading

Graph: solid arrow = fixes / best fix, dashed arrow = partial or unverified (see edge label); boxed group = PRs duplicating each other; amber border = best fix; indigo border = target; gray node = closed or no verify verdict yet (state tag in the node label).

Cross-PR triage: Reviewed 4 pull requests and 2 issues in this complex. Each diff was read against this issue; Assessment working set: 35 kB of PR diffs, 11 kB of issue/PR text, 5 kB of discussion (5 comments), 11 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.