Bug

The zsh completion script generated by hermes completion zsh fails when loaded via eval as the docs recommend:

# ~/.zshrc (per docs)
eval "$(hermes completion zsh)"

Error on shell startup:

_arguments:comparguments:327: can only be called from completion function

Root Cause

The generated script calls _hermes "$@" at the top level (line 28), which immediately invokes _arguments. When eval'd in .zshrc, this runs outside a completion context — _arguments is only valid inside a function triggered by zsh's completion system.

# Current output of `hermes completion zsh`:
_hermes() {
    ...
    _arguments \
        '-p[Profile name]:profile:($profiles)' \
        ...
}

_hermes "$@"    # <-- This line causes the error

Fix

Replace the trailing _hermes "$@" with a compdef registration, so the function is only called when the user tab-completes hermes:

_hermes() {
    ...
    _arguments \
        '-p[Profile name]:profile:($profiles)' \
        ...
}

compdef _hermes hermes    # <-- Register lazily instead of calling immediately

This is the standard pattern used by uv, kubectl, skaffold, and other tools that support eval "$(tool completion zsh)".

Workaround

Install the completion as a file instead of using eval:

mkdir -p ~/.oh-my-zsh/completions  # or ~/.zsh/completions
hermes completion zsh > ~/.oh-my-zsh/completions/_hermes
# Then remove the eval line from ~/.zshrc and source ~/.zshrc

Environment

• Hermes Agent v0.7.0 (2026.4.3) + 43 commits (latest main as of 2026-04-08)
• macOS 15.4, zsh 5.9, oh-my-zsh