hermes - 💡(How to fix) Fix [Bug]: Hermes macOS install/startup regression report

Bug Description

Searched existing GitHub issues; no prior report found for the self-referencing venv/bin/hermes launcher loop. Related but distinct: #6393, #5884, #8641.

I’m seeing what looks like a macOS install/startup regression that may overlap with #6393, but the immediate cause on my machine is more specific.

Symptoms:

• hermes hangs
• hermes --version hangs
• no usable startup output

This initially looked similar to #6393 ("after install it, startup failed"), but inspecting the installed files shows an infinite self-exec loop in the launcher.

What I found

~/.local/bin/hermes contains:

#!/usr/bin/env bash
unset PYTHONPATH
unset PYTHONHOME
exec "/Users/jagaliano/.hermes/hermes-agent/venv/bin/hermes" "$@"

That would be fine if the inner target were the real venv console script.

But ~/.hermes/hermes-agent/venv/bin/hermes also contains:

#!/usr/bin/env bash
unset PYTHONPATH
unset PYTHONHOME
exec "/Users/jagaliano/.hermes/hermes-agent/venv/bin/hermes" "$@"

So the inner launcher execs itself forever, which explains why:

• hermes hangs
• hermes --version hangs

Why this may be a regression

Git history suggests installer behavior changed:

Old scripts/install.sh at commit: 00192d51f1213625b8b89a78d7e03efbaf1d78b6

used:

ln -sf "$HERMES_BIN" "$command_link_dir/hermes"

Newer scripts/install.sh at commit: 043a118d4128e51480eb228d5085ad0366150c8a

message: fix: harden install.sh against inherited Python env leakage

changed that to:

cat > "$command_link_dir/hermes" <<EOF
#!/usr/bin/env bash
unset PYTHONPATH
unset PYTHONHOME
exec "$HERMES_BIN" "\$@"
EOF

That outer wrapper itself is reasonable.

The problem is that on my install, the venv’s own bin/hermes is not the expected generated Python console entrypoint and is instead another shell wrapper pointing to itself.

Expected

Per pyproject.toml, the real entrypoint should be generated from:

[project.scripts]
hermes = "hermes_cli.main:main"

So expected behavior is:

• ~/.local/bin/hermes can be a wrapper or symlink
• ~/.hermes/hermes-agent/venv/bin/hermes should be the real generated console script

Actual

• both are wrappers
• the inner wrapper execs itself forever

Conclusion

This may be related to the broader macOS install/startup failures in #6393, but the direct failure here appears to be a launcher/entrypoint generation bug causing an infinite loop.

Steps to Reproduce

N/A

Expected Behavior

Hermes agent start

Actual Behavior

Hermes hang forever

Affected Component

Other

Messaging Platform (if gateway-related)

Telegram

Debug Report

N/A

Operating System

MacOS Sequoia

Python Version

3.11.15

Hermes Version

latest from github

Additional Logs / Traceback (optional)

Root Cause Analysis (optional)

No response

Proposed Fix (optional)

No response

Are you willing to submit a PR for this?

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