Metadata-Version: 2.4
Name: hermes-plugin-pushary
Version: 0.3.1
Summary: Pushary push notifications plugin for Hermes Agent
Author-email: RalphNex OU <business@pushary.com>
License: MIT
Project-URL: Homepage, https://pushary.com
Project-URL: Repository, https://github.com/pushary/pushary
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Pushary Plugin for Hermes Agent

Push notifications and human-in-the-loop for [Hermes Agent](https://hermes-agent.nousresearch.com/) via [Pushary](https://pushary.com).

## Install

```bash
pip install hermes-plugin-pushary
```

Or manually (directory install — `plugin.yaml` and `skills/` ship inside the package):

```bash
cp -r pushary_plugin ~/.hermes/plugins/pushary
hermes plugins enable pushary
```

> **Note:** Hermes runs in its own virtualenv, so `pip install` must target that
> interpreter (e.g. `~/.hermes/hermes-agent/venv/bin/python -m pip install hermes-plugin-pushary`).
> `hermes plugins enable` currently only recognizes directory/bundled plugins, not
> pip-installed ones. If you installed via pip, enable it by adding the plugin to
> `~/.hermes/config.yaml` directly instead:
>
> ```yaml
> plugins:
>   enabled:
>     - pushary
> ```

## Setup

Set your API key:

```bash
export PUSHARY_API_KEY="pk_xxx.sk_xxx"
```

Get a key at [pushary.com/sign-up](https://pushary.com/sign-up?from=hermes).

## Tools

| Tool | Description |
|------|-------------|
| `pushary_notify` | Send a push notification with optional rich context |
| `pushary_ask` | Ask a question via push (yes/no, multiple choice, or free text) |
| `pushary_wait` | Wait for the user's answer |
| `pushary_cancel` | Cancel a pending question |

## Auto-Notifications

The plugin automatically sends push notifications when tools return errors (up to 3 per session).

Set `PUSHARY_AUTO_NOTIFY_SESSION_END=1` to also get notified when a session ends.

Set `PUSHARY_AGENT_NAME` to identify this Hermes instance in notifications (e.g., `"Hermes - daily-briefing"`).

## Permission Gating (approve from your lock screen)

Gate dangerous tools behind a yes/no push approval — Hermes pauses on a `pre_tool_call`
hook, pushes the request to your phone, and only runs the tool if you approve.

```bash
export PUSHARY_GATE_TOOLS="terminal,write_file,delete_file"   # comma-separated tool names
export PUSHARY_GATE_TIMEOUT_MS=55000                          # optional, max 55000
```

Behaviour for a gated tool:

| Outcome | Result |
|---------|--------|
| You approve | Tool runs |
| You deny | Tool is blocked, the agent is told why |
| No answer before timeout | Tool is blocked (fail-closed — you were asked) |
| Pushary unreachable / no API key | Tool runs (fail-open — never bricks on our outage) |

Gating is off unless `PUSHARY_GATE_TOOLS` is set. The Pushary tools themselves are never gated.

## License

MIT
