Metadata-Version: 2.3
Name: yoooclaw-hermes-plugin
Version: 0.1.0
Summary: YoooClaw tools and APP messaging platform adapter for Hermes Agent
Author: YoooClaw
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# hermes-plugin

YoooClaw integration for [Hermes Agent](https://hermes-agent.nousresearch.com/).

This repository is the Python plugin boundary between Hermes and YoooClaw.
The existing `@yoooclaw/cli` daemon remains responsible for the shared data
plane: phone notification ingest, recordings, images, Relay tunnels,
credentials, light-rule storage, and one-shot light control. The Hermes plugin
owns the APP conversation transport and the host-side light-rule trigger
runtime.

Production plugin artifacts bundle the platform-specific `yoooclaw` executable
itself. Users do not need a preinstalled CLI, and the plugin does not download
the CLI on first run. The embedded executable is verified and installed into a
plugin-managed path before use.

The release workflow downloads the four verified native assets from the pinned
`cli-v*` release in `YoooClaw/openclaw-plugin`, then creates one Python wheel per
platform. Each wheel carries only its own executable and a SHA-256 manifest:

```text
darwin-arm64
darwin-x64
linux-arm64
linux-x64
```

The wheels and `cli-wheel-index.json` are attached to the matching
`YoooClaw/hermes-plugin` GitHub Release. This keeps the Git repository small
while giving Hermes a package artifact that already contains the CLI.

Stable plugin releases also publish the platform wheels to PyPI. Hermes can
then discover both entry-point plugins after a normal package install:

```bash
pip install yoooclaw-hermes-plugin
hermes plugins enable yoooclaw
hermes plugins enable yoooclaw_app
```

## Initial Scope

- General Hermes plugin: tools, hooks, slash commands, CLI subcommands, skills.
- `yoooclaw_app` platform adapter: APP messages into Hermes and Hermes replies
  back to the APP.
- Tool bridge: call `yc --format json` and the daemon localhost HTTP API.
- Embedded CLI: ship the target platform's `yoooclaw` executable in the plugin
  artifact and use PATH lookup only as a local development fallback.
- APP transport: connect the Hermes platform adapter directly to the existing
  APP conversation channel without routing messages through the CLI daemon.
- Notification watcher: use OS file notifications on the active CLI profile's
  `notifications/` directory to feed newly persisted items into the host-side
  light-rule runtime without adding a daemon event API.

The initial commit exposes one working tool, `daemon_status`. The APP platform
adapter is a scaffold until its plugin-side `AppTransport` is implemented
against the existing APP / OpenClaw conversation contract.

## Layout

```text
yoooclaw_hermes/   # General Hermes plugin
yoooclaw_app/      # Hermes platform adapter for YoooClaw APP chat
tests/
```

## Development

Install [uv](https://docs.astral.sh/uv/getting-started/installation/) first, then:

```bash
uv sync --dev
uv run pytest
uv build
```

For local Hermes discovery, link the plugin directories into `~/.hermes/plugins/`
and enable them:

```bash
ln -s "$PWD/yoooclaw_hermes" ~/.hermes/plugins/yoooclaw
ln -s "$PWD/yoooclaw_app" ~/.hermes/plugins/yoooclaw_app
hermes plugins enable yoooclaw
hermes plugins enable yoooclaw_app
hermes plugins list
```

## References

- [Build a Hermes Plugin](https://hermes-agent.nousresearch.com/docs/guides/build-a-hermes-plugin)
- [Adding a Platform Adapter](https://hermes-agent.nousresearch.com/docs/developer-guide/adding-platform-adapters)
