clawhive-hermes-plugin 0.1.0

ClawHive platform adapter plugin for Hermes Agent

ClawHive Hermes Plugin

This plugin lets a Hermes runtime register as a ClawHive runtime node, sync Hermes profiles into ClawHive, receive ClawHive user messages through the Hermes platform adapter connection, and write Hermes replies back through the ClawHive message API. It is shaped for the Hermes directory plugin loader: plugin.yaml plus a root __init__.py that exposes register(ctx).

Install Locally

Copy this directory into a Hermes plugin path:

mkdir -p ~/.hermes/plugins/clawhive
cp -R hermes-plugin/* ~/.hermes/plugins/clawhive/

Install From a Local Wheel

The plugin is packaged as a Python distribution because Hermes plugins are Python modules. Build and install it locally before publishing to PyPI:

cd hermes-plugin
python -m build
python -m pip install dist/clawhive_hermes_plugin-0.1.0-py3-none-any.whl

Hermes can discover the package when the wheel is installed into the same Python environment that runs Hermes, through the hermes_agent.plugins entry point:

python - <<'PY'
import importlib.metadata as md
print(md.entry_points().select(group="hermes_agent.plugins")["clawhive"])
PY

For end-user installs where the package may be installed outside the Hermes virtual environment, use the packaged installer to create a normal Hermes directory plugin:

clawhive-hermes install
hermes plugins enable clawhive

Re-run with --force to replace an existing ~/.hermes/plugins/clawhive directory.

Authorize Locally

Enable the plugin in Hermes, then run the ClawHive authorization command:

hermes clawhive authorize \
  --project-url "https://<project>.supabase.co" \
  --anon-key "<anon key>"

This starts the same ClawHive device-code authorization flow used by the OpenClaw plugin: Hermes prints an approval URL and user code, the user approves with their ClawHive account, and the command stores the returned plugin token in the Hermes .env file. Restart the Hermes gateway after authorization so the platform adapter can call plugin-register and sync agents.

Status can be checked with:

hermes clawhive status

Required Runtime Environment

export CLAWHIVE_PROJECT_URL="https://<project>.supabase.co"
export CLAWHIVE_SUPABASE_ANON_KEY="<anon key>"
export CLAWHIVE_PLUGIN_TOKEN="<plugin token>"

Normally hermes clawhive authorize writes these values to $HERMES_HOME/.env; set them manually only for local testing or automation.

Optional values:

export CLAWHIVE_NODE_NAME="Hermes Desktop"
export CLAWHIVE_PLUGIN_VERSION="0.1.0"
export CLAWHIVE_USER_ID="<user uuid>"
export CLAWHIVE_PLUGIN_NODE_ID="<existing node uuid>"

Agent Registration

ClawHive follows the Hermes platform plugin flow. Hermes loads plugin.yaml, calls register(ctx), and creates ClawHivePlatformAdapter through ctx.register_platform(...). When the adapter connects, it registers the Hermes runtime node with ClawHive and syncs serviceable Hermes profiles as ClawHive agents.

Hermes profiles are discovered through Hermes profile APIs. With gateway profile multiplexing enabled, the adapter syncs all serviceable profiles. Without multiplexing, it syncs the active/default profile only.

Message Routing

ClawHivePlatformAdapter.send(chat_id, text) writes an agent message with:

chat_id = <session_id>:<agent_id>

If Hermes supplies session metadata separately, pass session_id and agent_id as keyword arguments instead of encoding them into chat_id.

Inbound messages are received by the platform adapter's connect() flow through the ClawHive Realtime bridge. The adapter converts user messages into Hermes MessageEvent values and dispatches them through self.handle_message(event).

poll_session(session_id) is a local debug/fallback helper. It is not the product message receive path.

Local Verification

From the repository root:

python3 -m pytest hermes-plugin/tests