Skip to content

docs(hermes): describe the directory-plugin install the bootstrap performs - #34

Open
nir-singher-band wants to merge 1 commit into
mainfrom
docs/hermes-directory-plugin-install
Open

nir-singher-band wants to merge 1 commit into
mainfrom
docs/hermes-directory-plugin-install

Conversation

@nir-singher-band

Copy link
Copy Markdown
Collaborator

Why

Follow-up to #21. hermes/README.md and hermes/TESTING.md still described the pip install into the gateway Python that bootstrap.sh stopped doing when it moved to the repo's install.sh (directory plugin). Two were actively broken instructions:

  • TESTING.md told you to swap in uv pip install --python "$hermes_python" -e … — $hermes_python is defined by no script in the repo any more.
  • The Part 2 verification snippet resolved the skill via import hermes_band_platform, which a directory install cannot satisfy: the plugin is copied to $HERMES_HOME/plugins/band, not installed into the gateway venv.

What changed

Both guides now state what the install actually does, per upstream install.sh:

  • stage the plugin into $HERMES_HOME/plugins/band, resolve band-sdk into $HERMES_HOME/band-libs with the gateway interpreter, write nothing to the gateway venv, enable band;
  • resolve the skill by path and the interpreter with the plugin's own gateway_python.py --print — the way install.sh and bootstrap.sh both do it.

Constraints that follow, now recorded:

  • a directory plugin is a copy, so local plugin edits need install.sh re-run — there is no editable install;
  • a pip copy of hermes-band overrides a directory install in Hermes's loader, so install.sh refuses to run while one is present (BAND_UNINSTALL_PIP=1 removes it);
  • verify_install.py lists package_importable/entry_point under missing on a correct directory install, so blocking is the field to read. Checklist and troubleshooting updated accordingly.
  • uv added to the TESTING prereqs — install.sh hard-requires it for uv pip install --target.

The setup skill is addressed as band:add-band, matching the hand-off bootstrap.sh runs. The previous hermes /add-band had nothing behind it: the band plugin registers no slash command (no register_slash_command in the plugin), and bootstrap.sh documents that plugin skills never enter the flat ~/.hermes/skills tree.

Docs only — no change to bootstrap.sh or scripts/.

Test plan

  • python3 scripts/check.py
  • pytest tests/ -q (17 passed)
  • The new Part 2 snippet executed against the real upstream gateway_python.py in an installed-layout tree: resolves ~/.hermes/hermes-agent/venv/bin/python, Python 3.11.15, hermes_cli importable — matching the installer's 3.11–3.13 + hermes_cli contract.
  • Every claim checked against upstream install.sh / verify_install.py rather than the previous prose.

…forms

The guides still described the pip install into the gateway Python that
bootstrap.sh stopped doing when it moved to the repo's install.sh: an
editable `uv pip install --python "$hermes_python"` against a variable no
script defines any more, and a Part 2 snippet resolving the skill through
`import hermes_band_platform`, which a directory install cannot satisfy
because the plugin is copied to $HERMES_HOME/plugins/band.

State what the install does: stage the plugin into $HERMES_HOME/plugins/band,
resolve band-sdk into $HERMES_HOME/band-libs with the gateway interpreter,
write nothing to the gateway venv, enable the plugin. Resolve the skill by
path and the interpreter with the plugin's own `gateway_python.py --print`,
the way install.sh and bootstrap.sh do. Record the constraints that follow:
a directory plugin is a copy, so local edits need install.sh re-run rather
than an editable install; a pip copy of hermes-band overrides a directory
install, which install.sh refuses; and verify_install.py reports
package_importable/entry_point under `missing` on a correct directory
install, so `blocking` is the field to read.

Address the setup skill as `band:add-band`, matching the hand-off
bootstrap.sh runs. The band plugin registers no slash command, so the
previous `hermes /add-band` had nothing behind it.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant