https://github.com/nilp0inter/hermes-zello-plugin
Zello platform plugin for NousResearch hermes-agent — long-form voice memo channel for nil-agent.
https://github.com/nilp0inter/hermes-zello-plugin
Last synced: about 1 month ago
JSON representation
Zello platform plugin for NousResearch hermes-agent — long-form voice memo channel for nil-agent.
- Host: GitHub
- URL: https://github.com/nilp0inter/hermes-zello-plugin
- Owner: nilp0inter
- Created: 2026-05-26T00:12:01.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-03T11:17:53.000Z (about 2 months ago)
- Last Synced: 2026-06-03T12:21:51.359Z (about 2 months ago)
- Language: Python
- Size: 158 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# hermes-zello-plugin
Zello Channel API platform plugin for [Hermes Agent](https://github.com/NousResearch/hermes-agent).
Long-form voice memos in, short clarifying questions / action proposals out.
PTT-driven, half-duplex. Voice-only in v1.
## Architecture
Inbound: Zello channel → aiozello WebSocket → per-user utterance aggregator
(handles the ~60 s phone-app PTT segmentation) → Ogg-Opus packaged via
ffmpeg → Hermes `MessageEvent(message_type=MessageType.VOICE)` → Groq STT
→ agent → text reply.
Outbound: text → Hermes TTS (ElevenLabs) → audio file → ffmpeg PCM decode →
opuslib re-encode → aiozello outbound stream with realtime pacing → Zello
channel.
See `HERMES-ZELLO-PLAN.md` for the full design report and `DELTAS.md` for
deviations discovered during implementation.
## Install
The plugin is consumed as a tree under `~/.hermes/plugins/zello/`. Hermes
discovers `plugin.yaml` and imports `hermes_zello_plugin.register(ctx)`.
For local development:
```
nix develop
uv sync
uv run pytest
```
`flake.nix` ships a devShell with `python3`, `uv`, `ffmpeg-headless`, and
`libopus` (on `LD_LIBRARY_PATH` for `opuslib`'s ctypes loader).
## Configure
See `.env.example` for the full env-var surface. Required:
- `ZELLO_ISSUER`, `ZELLO_PRIVATE_KEY_PATH`, `ZELLO_USERNAME`, `ZELLO_PASSWORD`,
`ZELLO_CHANNEL`.
Optional:
- `ZELLO_ALLOWED_USERS`, `ZELLO_ALLOW_ALL_USERS`, `ZELLO_HOME_CHANNEL`,
`ZELLO_AGGREGATOR_WINDOW_S` (default 2), `ZELLO_MAX_UTTERANCE_S` (default
300).
Out-of-band setup checklist: `SETUP.md`.
## Tools
- `end_session` (`session-control`): ends the current live Zello voice session
with Hermes `/new` parity. Intended as the final tool call after a
voice-session close such as `cambio y corto`.
## Test
```
uv run pytest -q
```
Tests stub `gateway.*` modules so they run without a `hermes-agent`
checkout.
## License
Apache-2.0.