hermes - 💡(How to fix) Fix [Bug]: Homebrew / packaged installs advertise --tui but crash because ui-tui is not included in the installed package [1 pull requests]

Bug Description

Summary

hermes --tui crashes in a Homebrew install because the packaged install does not contain the ui-tui directory that the CLI expects.

Environment

• macOS
• Homebrew install of hermes-agent
• hermes --version: Hermes Agent v0.13.0 (2026.5.7)
• Python in formula: 3.14.4
• Node: v26.0.0
• npm: 11.12.1

What I verified

1. The installed Homebrew tree contains:

• hermes_cli
• tui_gateway

but does NOT contain:

• ui-tui

1. The Homebrew formula currently just does:

• virtualenv_install_with_resources

and does not explicitly package/copy ui-tui

1. Upstream source checkout DOES contain:

• ui-tui/package.json
• ui-tui/src/entry.tsx

1. Built upstream Python artifacts do NOT contain ui-tui

I built both:

• hermes_agent-0.13.0-py3-none-any.whl
• hermes_agent-0.13.0.tar.gz

and found zero ui-tui entries in either artifact.

Conclusion

This looks like a packaging bug, not a local Node/npm issue:

• repo checkout can run the TUI because ui-tui/ exists
• Python-packaged installs omit ui-tui/
• Homebrew inherits that omission

Notes

I also tested a repo-based editable install (uv pip install -e .) and the TUI starts there under a PTY, which supports the diagnosis that the issue is asset omission in packaged installs.

Steps to Reproduce

1. Install Hermes from Homebrew
2. Run: hermes --tui

Expected Behavior

If --tui is advertised in hermes --help, it should either:

• work in packaged installs, or
• fail gracefully with a clear packaging error, not a traceback

Actual Behavior

It crashes with:

FileNotFoundError: [Errno 2] No such file or directory:
'/opt/homebrew/Cellar/hermes-agent/2026.5.7/libexec/lib/python3.14/site-packages/ui-tui'

Traceback shows _launch_tui() -> _make_tui_argv() trying to run npm in: PROJECT_ROOT / "ui-tui"

Affected Component

CLI (interactive chat)

Messaging Platform (if gateway-related)

No response

Debug Report

Report       https://paste.rs/eM0Lj
agent.log    https://paste.rs/jC9Qn
gateway.log  https://paste.rs/vGIBS

Operating System

macOS 26.4.1 (25E253)

Python Version

3.14.4

Hermes Version

0.13.0

Additional Logs / Traceback (optional)

Root Cause Analysis (optional)

No response

Proposed Fix (optional)

Any of these would solve it:

1. Include ui-tui in the Python package / distributable artifacts
2. Have the Homebrew formula explicitly vendor/copy the TUI assets
3. Make --tui detect missing assets and print a clear error like: "This install does not include the bundled TUI assets; use a source checkout or set HERMES_TUI_DIR"

Are you willing to submit a PR for this?

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