@pushary/agent-hooks

Push notifications, questions, and permission approvals for AI agents. Get a push when your agent finishes work, answer its questions from your phone, and approve risky commands before they run. Works with Claude Code, Codex, Cursor, VS Code, OpenCode, Gemini CLI, and Hermes.

Your agent froze waiting for a yes. This is how it reaches you.

npx @pushary/agent-hooks@latest setup

One command wires up the MCP server, the permission hooks, and the agent instruction files. Then you close your laptop and the agent still reaches you.

What it does

There are three things.

Notify. The agent sends a push when a long task finishes or when a build, test, or deploy fails. The notification can carry what changed, the error, and suggested next steps.

Ask. The agent asks you questions through push: yes/no, multiple choice, or free text. It waits for your answer. When Pushary is connected, the agent sends its questions to your phone instead of stalling in the terminal.

Gate. Risky shell commands (rm -rf, force pushes, history rewrites, database drops, deploys) are checked before they run. What happens is set by your dashboard policy: auto approve trusted read-only commands, push to your phone for approval, or hold for the phone and never auto-deny. If the check cannot run, the decision falls back to the agent's own permission prompt in the terminal; nothing is silently allowed. Without an API key configured, the hooks stay out of the way entirely and only count what they would have gated.

Just want a bell? That part is free.

If your agent runs in front of you and you only need to know when it finishes, you do not need any of the above and you should not pay for it:

npx @pushary/agent-hooks@latest bell

That is the whole thing. It makes a noise in your terminal and raises a desktop notification when Claude Code says an agent finished or is waiting on you. It rides Claude Code's own notification events, so it fires when you have actually stepped away rather than after every reply. No account, no API key, no network call, nothing leaves your machine. Turn it off with pushary bell --off; it touches nothing else in your settings.

If you landed here from error: unknown option '--global'

You probably ran this, from a blog post or an answer somewhere:

claude config set --global preferrednotifchannel terminal_bell
error: unknown option '--global'

claude config set no longer takes --global. The setting moved into ~/.claude/settings.json, so the direct equivalent is to put it there yourself:

{ "preferredNotifChannel": "terminal_bell" }

That rings on Claude Code's own notification events. pushary bell does the same job through a hook instead, which means it also fires on Stop (the agent finished, which is the case most people actually want) and can raise a real desktop notification rather than only a beep. Either is fine. Neither costs anything.

Where the free part stops

A bell has a ceiling, and the ceiling is how many agents you run:

• One agent. A bell is perfect. Pushary is overkill and we would rather you did not buy it.
• Two or three. The bell rings and you cannot tell which agent. You alt-tab looking for it.
• Four or more. The bell is noise, and you have left the room anyway.

Above three concurrent agents the bell says so, once a day, and then stops talking. Set PUSHARY_BELL_QUIET=1 if you would rather it never mentioned it.

Setup

Run setup:

npx @pushary/agent-hooks@latest setup

It shows a QR code and short link. Open either in the Pushary app, check that the fingerprint matches, and approve. Setup then stores the credential and configures the agents it detects. If this machine already has a key, setup reuses it and skips pairing.

For CI or another non-interactive install, pass an existing key explicitly:

npx @pushary/agent-hooks@latest setup --key pk_xxx.sk_xxx --skip-phone

Verify it worked:

npx @pushary/agent-hooks@latest doctor

Supported agents

| Agent | Notify | Ask | Gate | |-------|:------:|:---:|:----:| | Claude Code | yes | yes | yes | | Codex | yes | yes | yes | | Cursor | yes | yes | yes | | Gemini CLI | yes | yes | yes | | Hermes | yes | yes | yes | | VS Code | yes | yes | yes | | OpenCode | yes | yes | yes |

Any other MCP client can use notify and ask by pointing at the Pushary MCP endpoint directly.

Control an agent from your phone

The Pushary app can start an agent on a connected computer and send instructions to a running session. It is deliberately not a remote shell: the phone submits a task to the selected agent, and the agent still runs with its normal permissions, hooks, and approval policy on your computer.

| Control | Claude Code | Codex | Gemini CLI | Other agents | |---------|:-----------:|:-----:|:----------:|:------------:| | Start a new session | yes | yes | yes | no | | Send an instruction to a live session | yes | yes | yes | wrapper-dependent | | Approve, deny, and answer | yes | yes | yes | yes via MCP |

Requirements and limits:

• Run setup once. It installs a per-user background service using LaunchAgent on macOS, systemd on Linux, or Task Scheduler on Windows.
• The computer must be awake, logged in, online, and have the selected agent CLI installed. Pushary advertises only providers it finds on that machine.
• Start and Send require Face ID, Touch ID, or the device passcode. Controls are hidden when the machine or session has no recent live consumer.
• An instruction may remain queued on Pushary's server for up to one hour while delivery retries. It is delivered to the agent session, never executed as a raw terminal command.
• Agent control requires a paid plan after the trial. Current terms are on the pricing page.

Service lifecycle is explicit and cross-platform:

pushary daemon status
pushary daemon install
pushary daemon stop
pushary daemon restart
pushary daemon uninstall

pushary setup installs and verifies the service. pushary upgrade refreshes it, and pushary clean stops and removes it.

Hook events, gated by version

Claude Code 2.1.239 names thirty-one hook events and the set grows release by release, so the ones we register are gated on the version actually installed. The version is read from disk and never by running the binary: codex --version once submitted the Codex CLI to XProtect, which killed it and moved the 181 MB binary to the Trash, so setup deleted the user's installation as a side effect of asking its version.

An unreadable version registers only the events that predate gating. Each registration records registered|<version>, which is what lets an upgrade pick up newer events without anyone re-running setup.

Admission rules

Publishing this package is a version bump merged to main, and a hook change is not live until that happens, so a hook that floods on one event would otherwise need a release to stop. ~/.pushary/admission-rules.json can disable an (agent, event) pair as data.

Deny-only by construction: a rule can silence a hook we ship, and no shape of the file can enable one we do not. A file that cannot be read admits everything, because failing closed would let one malformed download silence every hook on the machine.

Commands

cowork       Set up Claude Desktop and Cowork with the Pushary connector
setup        Configure Claude Code, Codex, Gemini CLI, Hermes, Cursor, VS Code, or OpenCode with Pushary
claude       Run Claude Code through Pushary, reachable from your phone even when idle
daemon       Keep this machine reachable so your phone can START a new session
status       One screen: which key is in force, whether the server accepts it, what can receive an approval
login        Sign in from this terminal, no key to copy (--with-token to pipe one in)
logout       Remove the key this machine stores, and say what it does not remove
connect      Connect a phone without re-running setup (--app for the Pushary app)
bell         Free local bell when an agent finishes or needs you. No account, no key, no network
doctor       Verify your Pushary installation is working
disconnect   Turn off one agent (claude|codex|gemini|cursor)
clean        Remove Pushary from this machine (--everything: the Mac app's setup too, --dry-run: preview)
mode         Choose where approval requests appear
wait         Show or set the "wait for your phone" ladder (pushary wait 45)
stats        Show the approval moments your agents hit while not connected
suggestions  List rules mined from your own approvals
upgrade      Update the globally installed hooks to the latest version
hook         Run as a PreToolUse hook (reads stdin, writes stdout)
transcripts  Show or re-trust the keys this machine seals transcripts to

Run pushary <command> --help for one command's options.

Non-interactive setup

setup asks which agents you use, so a run with no terminal on stdin needs to be told instead. --agents or --yes does that; without either, setup takes the defaults rather than waiting for a keypress that can never arrive.

# Everything detected on this machine, no prompts
npx @pushary/agent-hooks@latest setup --key-stdin --yes --skip-phone < key.txt

# Named agents only
npx @pushary/agent-hooks@latest setup --agents claude_code,codex --yes --skip-phone

# Store the key and configure nothing
npx @pushary/agent-hooks@latest setup --agents none --yes

# Show what would be written, change nothing
npx @pushary/agent-hooks@latest setup --agents auto --dry-run

# One machine-readable object on stdout; every human line goes to stderr
npx @pushary/agent-hooks@latest setup --agents auto --yes --json

Prefer --key-stdin over --key in CI: --key puts the secret in argv, where any other user on the box can read it out of ps.

Exit codes: 0 done, 2 bad usage, 3 no key resolvable, 4 the server rejected the key, 5 finished with problems (an inactive plan, or an installer that failed), 130 cancelled with Ctrl-C.

Examples:

npx @pushary/agent-hooks@latest mode push_only --for 30m
npx @pushary/agent-hooks@latest wait 45
npx @pushary/agent-hooks@latest clean

Updates

From 1.5.0, Pushary updates itself. When an agent session starts, the session-start hook checks at most once a day whether a newer version is published. If one is, it installs that version in the background into the same global npm folder your hooks already run from, then refreshes each agent's config the way pushary upgrade does. The session does not wait for it, and the new version runs from the next hook call.

• It stays within the same major version. A new major shows in pushary doctor, and you move to it with npx @pushary/agent-hooks@latest upgrade.
• It only updates a global npm install. A copy run through npx, a plugin, or the Mac app updates by its own route.
• It never uses sudo. If npm cannot write to the global folder, the attempt is recorded as failed and nothing changes.
• It does not run on Windows yet, or when CI is set. Linux automatic updates are paused because restarting the systemd daemon can terminate phone-started sessions. On Linux, finish running sessions before upgrading manually.
• If installation succeeds but configuration refresh fails, the next automatic check or manual upgrade retries the refresh before checking for another release.

Turn it off with either of these:

pushary upgrade --auto=off           # turn it back on with --auto=on
export PUSHARY_DISABLE_AUTOUPDATE=1  # in the environment your agents start from

pushary doctor shows whether it is on and the result of the last check. The state is kept in ~/.pushary/auto-update.json, and the output of recent updates in ~/.pushary/logs/auto-update.log.

Manual MCP setup

If you only want notifications and questions (no permission gating), add Pushary to your MCP config directly:

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

The MCP server exposes send_notification, ask_user, wait_for_answer, and cancel_question. Full tool reference is in the docs.

Security

If a policy cannot be fetched or a hook errors, the decision falls back to the agent's native permission prompt, never a silent allow. The Cursor gate is the strictest surface: it blocks matched risky commands outright when its check cannot run. Secrets in command arguments and environment are redacted before anything is sent to a phone or stored. Read-only commands can be allowlisted so trusted work never interrupts you, while writes and destructive commands still route through approval.

Links

• Website: pushary.com
• Docs: pushary.com/docs
• Sign up: pushary.com/sign-up
• Troubleshooting: pushary.com/docs/agents/reference/troubleshooting
• Support and bug reports: Discord or [email protected]

License

MIT

Claude Desktop and Cowork

Run pushary cowork (or npx @pushary/agent-hooks@latest cowork) for connector setup. pushary setup --agents cowork opens the same setup path without storing a CLI key or writing hooks. Add the OAuth URL in Claude and sign in with the account used by your Pushary phone/Mac app.

Use pushary cowork --instructions for standing instructions or pushary cowork --skill > SKILL.md to export the bundled skill for upload. --json reports manual_setup_required; printing a link does not prove a connection. Ask a test question in Claude, answer it in Pushary, and verify Claude receives it.

This connector is cooperative. Cowork supports plugin hooks on supported versions, but this setup does not install or verify native permission hooks. Use the normal setup command for Claude Code CLI hooks.