| name | pi-agent-hermes-tool |
| description | Hermes-native tool plugin for controlling pi --mode rpc sessions with full lifecycle management |
| version | 1.0.0 |
| author | Dustin Chadwick (@ShaggyD) |
| license | MIT |
| tags | ["hermes","pi-agent","rpc","tool-plugin","session-management"] |
Pi Agent - Hermes Tool Plugin
Native Hermes tool plugin for controlling pi --mode rpc sessions. Provides the pi_agent tool within Hermes for full session lifecycle management.
Problem
Running pi in RPC mode from within Hermes meant manually launching subprocesses, managing session files, reading JSON event streams, and handling auth failures. Every session required wiring up stdin/stdout, tracking session state yourself, and reconnecting when things broke. There was no reusable, tested interface.
Built
A Hermes tool plugin (tools/pi_agent_tool.py) with a companion test suite that wraps the entire pi RPC protocol. Provides a single pi_agent tool with these actions:
- start - Launch a new pi RPC session in a project directory
- resume - Reconnect to an existing session file
- send - Send a message or command to the active session
- poll - Fetch new events since last check
- wait - Block until the session completes its turn
- stop - Terminate a session cleanly
- list - View active sessions
Outcome
No more manual process management or raw JSON line parsing. Pi RPC sessions are as easy to use as any other Hermes tool. Sessions survive restarts, auth reconnects, and network interruptions without losing context. The test suite validates against the actual pi protocol so edge cases and auth failures are handled cleanly.
Installation
This plugin is registered in the Hermes agent's tool configuration. Ensure the pi_agent_tool.py file is accessible from the Hermes tools directory.
cp tools/pi_agent_tool.py ~/.hermes/tools/
pi --version
Files
| File | Purpose |
|---|
tools/pi_agent_tool.py | Main Hermes tool plugin for pi RPC |
tools/test_pi_agent_tool.py | Test suite against the pi protocol |
scripts/pi_agent_client.py | Helper client for pi RPC communication |
Usage
pi_agent action=start workdir=/path/to/project
pi_agent action=send session_id=abc message="build the feature"
pi_agent action=wait session_id=abc timeout=120
pi_agent action=stop session_id=abc
See Also
