Pushary: human-in-the-loop for AI agents

Pushary: human-in-the-loop for AI agents

Push notifications and human-in-the-loop for AI agents. Approve from your phone.

Get started · Skills directory · Report a bug

Start here

[Try an approval without signing up](https://pushary.com/try?utm_source=github&utm_medium=oss-skill&utm_campaign=pushary-skill&utm_content=demo) → connect an open phone page → approve or decline → see the agent continue or stop. This browser demo uses polling and temporary state, not real push delivery or the production ledger.

The skill and adapters are MIT-licensed. Hosted phone delivery requires a Pushary account; embedding approvals for your own users requires Partner access. The two framework examples also run locally with simulated answers and no credentials.

If Pushary helped you, star this repo. Want to help? Public issues and patches are welcome.

---

Pushary lets your coding agent send task updates and ask you for a decision on your phone. Supported host hooks also enforce approvals before an action runs.

Hosted delivery requires a paid Pushary plan. MCP questions and notifications work with any compatible client; enforced approvals depend on the host integration.

How It Works

AI Agent  ->  MCP Protocol  ->  Pushary API  ->  Push Notification  ->  Your Phone

Pushary is an MCP server that connects your AI coding agent to push notifications. The agent calls Pushary's tools over the Model Context Protocol, and you receive notifications instantly on any device.

Three question types - yes/no confirmations, multiple choice, and free text input. Your agent picks the right one for the situation.

Rich context notifications - agents can include file changes, error details, and suggested next steps in a detail page you see when tapping the notification.

Agent identification - when you run multiple agents, each notification shows which agent is asking so you always know what you're responding to.

Permission hooks - route Claude Code's tool approval prompts through push notifications so you can approve or deny from your phone.

---

Personal setup: phone first

Run the pairing setup in your agent's terminal:

npx pushary@latest setup

Install Pushary on your phone, scan the QR or open the printed link, compare the fingerprints, and approve. Setup then configures the selected agent's tools, supported hooks and skill. You do not need to copy an API key first. Personal accounts require a paid plan. Existing credentials are reused.

Verify setup:

npx pushary@latest doctor

Ask your agent for one harmless test question. Confirm the intended device receives it and the answer returns to the same task.

For Hermes specifically:

npx pushary@latest setup --agents hermes

This writes the native plugin to ~/.hermes/plugins/pushary and turns it on with hermes plugins enable pushary and hermes config set. Restart Hermes afterward with hermes gateway restart. The plugin provides notification, question, wait, cancel, reminder and scope tools, plus Partner enrollment and customer-question tools. Its parameters use snake_case; use the Hermes skill, not MCP parameter names. The native approval transport preserves Hermes' session and standing approvals.

Mac notch and other answer surfaces

Install Pushary for Mac, sign in with the same personal account and connect your agents from the app. The notch provides confirm, choice, text and question-set controls with keyboard support. Keep the app running for presence and delivery; verify one harmless question there, then phone fallback while away from the Mac.

Delivery follows your settings and presence. push_first uses presence, push_only requests push every time, notify_only keeps decisions in the current client, and terminal_only avoids push. A successful API call alone does not prove a device displayed the request.

Partner setup: your own customers

Personal pairing connects you, the operator. Partner integrations enroll each of your application's customers through a scoped connection link and address decisions using your stable customer ID. Customers use the mobile enrollment flow; do not route their approvals to your personal Mac inbox or share an operator API key.

Start with the Partner integration guide, then a Mastra agent example, AI SDK example or LangGraph example. Tools choose confirm, choice or text. Approving an action and supplying an answer are different operations; a text answer saying “yes” is not permission to execute another tool.

Manual fallback

For a client that needs manual MCP configuration, obtain your key in the Pushary dashboard and configure:

{

"mcpServers": { "pushary": { "url": "https://pushary.com/api/mcp/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } }

Keep the key private. Install the skill with npx skills add Pushary/pushary-skill if the client supports skills.sh. Manual MCP provides cooperative questions and notifications; enforced approvals require the supported host hooks/runtime integration.

Claude Code users can alternatively install this repository as a plugin:

/plugin marketplace add Pushary/pushary-skill

/plugin install pushary

That path reads PUSHARY_API_KEY from the environment. Pick one installation path: installing the plugin on top of CLI-installed Claude hooks can run hooks twice. Use npx pushary@latest clean before switching paths.

The plugin starts each hook through npx, which is too slow for the hook that streams live reply previews to your phone, so the plugin leaves that hook out. For live previews, install with npx pushary@latest setup instead. Setup installs every hook as a local command.

---

Setup: Lovable

Lovable is a hosted app builder, so there is no local install step (npx skills add does not apply). You connect the MCP server in Lovable's UI, then paste the skill into Lovable's Knowledge so the agent uses it on its own.

1. Connect the MCP server. In Lovable, go to Settings -> Connectors -> Personal connectors (paid Lovable plans), click New MCP server, set the URL to https://pushary.com/api/mcp/mcp, choose Bearer token, and paste your API key (pk_xxx.xxx).

2. Add the skill to Knowledge. Lovable cannot install skills via npx, so paste the skill guidance into Settings -> Knowledge. Use the condensed SKILL-LITE.md as the source. This makes the Lovable agent notify you when a build finishes and ask before risky changes, without you prompting each time.

Lovable gets notifications and questions only (no enforced gate, since it has no permission hook). Full walkthrough: Lovable guide.

---

Setup: Claude Chat and Cowork

For Claude Chat or Claude Code, use Pushary for Claude. In Chat, open Customize > Plugins > Add > Add marketplace, add https://github.com/Pushary/claude-plugin, and install Pushary for Claude. In Claude Code, run /plugin marketplace add Pushary/claude-plugin, then /plugin install pushary@pushary-claude-plugin.

For Cowork, the existing Pushary for Cowork plugin remains available. Add https://github.com/Pushary/cowork-plugin as the marketplace and install Pushary for Cowork. Cowork also supports standing instructions under Settings > Cowork. Its existing plugin, marketplace, and pushary-cowork skill identifiers are preserved.

Both bundles use the public OAuth connector and the same shared skill. Connect Pushary from the plugin's Connectors tab in Chat or Cowork, or /mcp in Claude Code, and sign in with the same Pushary account used by your phone or Mac. No CLI or API key is needed for either bundle.

If the connector is missing, add https://pushary.com/api/mcp/mcp under Customize > Connectors > Add custom connector and leave the OAuth Client ID and Secret fields empty. Enable Pushary in the conversation, ask one harmless test question, and verify your answer returns to Claude.

These bundles provide questions and notifications and install no native permission hooks. For Claude Code approval hooks, use the Claude Code setup above. Choose one installation path per app to avoid duplicate Pushary connectors. Full Claude guide.

---

Tools

The skill guides these MCP tools:

| propose_scope | Ratify the boundary of a run: file globs