Hermes Agent Deep Cuts: Tab Completion Knows Your Profiles, Not Your Config
Part of the Hermes Agent: Deep Cuts series

Hermes Agent Deep Cuts: Tab Completion Knows Your Profiles, Not Your Config

Run hermes completion bash and you get a shell script that completes Hermes commands and subcommands. The interesting part is that it does not ask Hermes for suggestions every time you press Tab. Most of the command tree is baked into the script when you generate it. Profile names are the exception: the shell function checks the profiles directory when completion runs.

That split matters when you update Hermes, switch profiles, or run with a non-default home. A completion script can stay syntactically valid while suggesting a command from an older install, or fail to offer a profile that Hermes itself can use.

Two different sources of truth

The CLI’s completion command selects a generator for bash, zsh, or fish and prints its result. The generator in hermes_cli/completion.py walks the already-built argparse parser tree. It extracts subcommand names and option strings, then writes shell-specific completion code. There is no extra shell-completion package involved.

For the command tree, that means generation time is the snapshot boundary. Regenerate the script after an update if you want completions for newly installed CLI commands. The emitted script does not launch Hermes to refresh the tree on every keypress.

Profile completion follows a different path. The generated shell function enumerates $HOME/.hermes/profiles when you request a completion after -p or --profile. That keeps profile names current without regenerating the script, but it also assumes the profiles live under that directory. If the CLI is pointed at a different HERMES_HOME, the completion helper does not consult that setting in the code examined here.

Install it without freezing the command list

For bash or zsh, evaluate the output during shell startup instead of appending it to a file once:

# ~/.bashrc
command -v hermes >/dev/null && eval "$(hermes completion bash)"
# ~/.zshrc
(( $+commands[hermes] )) && eval "$(hermes completion zsh)"

Fish has its own startup mechanism:

hermes completion fish > ~/.config/fish/completions/hermes.fish

With the bash and zsh snippets, the generated command tree is refreshed whenever a new interactive shell starts. The profile names are checked later, at completion time. Fish reads a generated completion file, so rerun the command after updating Hermes.

To inspect what a shell will load without touching your startup files:

hermes completion bash > "$HOME/.cache/hermes-completion.bash"
bash -n "$HOME/.cache/hermes-completion.bash"
grep -n 'profile names after' "$HOME/.cache/hermes-completion.bash"

The same inspection works for zsh with zsh -n. On the inspected installation, both parsers accepted their generated scripts. Fish syntax checking needs the fish executable, which was not installed in this environment, so I could not verify that one with its own parser.

The gotcha is a second home directory

A profile can be selected through hermes -p work, and Hermes supports profile homes. But the generated helper’s profile discovery is a shell function that reads $HOME/.hermes/profiles, not a call to the Hermes profile resolver. Those are normally aligned. With a custom HERMES_HOME, container home, or service environment, they can differ.

If hermes -p work works but Tab does not suggest work, inspect the generated helper and compare its directory with the active Hermes home. The completion script is a convenience layer, not an authoritative profile inventory.

The command list has its own failure mode. A script saved once is not automatically updated when Hermes grows new subcommands. Re-run hermes completion <shell> after an update, or evaluate it on shell startup. Do not mistake a successful syntax check for a fresh command list.

Verify the installed path

Generate the script and parse it before wiring it into your shell:

hermes completion bash > "$HOME/.cache/hermes-completion.bash"
bash -n "$HOME/.cache/hermes-completion.bash"

Then verify the profile helper points where you expect:

grep -n '\.hermes/profiles' "$HOME/.cache/hermes-completion.bash"

For zsh, use hermes completion zsh and zsh -n. For fish, write the generated output to ~/.config/fish/completions/hermes.fish, then check it with fish -n on a machine where fish is installed.

The shell script is a cached view of the parser, not a live Hermes API. Keep the generator close to startup if command freshness matters. Check the profile path separately, because that part is read at a different time.

Sources

Evidence notes

Observed in the installed Hermes source: the CLI selects one of three shell generators; the generator walks an argparse parser tree; the bash and zsh profile helpers inspect $HOME/.hermes/profiles at completion time. I ran the generated bash and zsh scripts through their shell syntax checkers successfully. Fish was unavailable, so its parser check was skipped.

Inference: evaluating generated bash or zsh completion at shell startup refreshes the embedded command tree on each new shell, while profile discovery remains deferred until a completion request. This follows from the generated code, not a timing benchmark.

Keep reading