# @pushary/agent-hooks

[![npm version](https://img.shields.io/npm/v/@pushary/agent-hooks.svg)](https://www.npmjs.com/package/@pushary/agent-hooks)
[![npm downloads](https://img.shields.io/npm/dm/@pushary/agent-hooks.svg)](https://www.npmjs.com/package/@pushary/agent-hooks)
[![license](https://img.shields.io/npm/l/@pushary/agent-hooks.svg)](./LICENSE)

Push notifications, questions, and permission approvals for AI coding 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, Gemini CLI, and Hermes.

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

```bash
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:

```bash
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:

```json
{ "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

You need an API key. Sign up at [pushary.com](https://pushary.com/sign-up?from=npm), then run:

```bash
npx @pushary/agent-hooks@latest setup
```

The wizard detects which agents you have installed and configures each one. To skip the prompts:

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

Verify it worked:

```bash
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 |

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

## 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

<!-- Managed: every command below is declared in src/cli/commands.ts, and a test
     asserts this list matches it. Do not edit one without the other. -->

```
setup        Configure Claude Code, Codex, Gemini CLI, Hermes, Cursor, or VS Code 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 all Pushary configuration (--yes for non-interactive)
mode         Switch approval mode (push_only, push_first, terminal_only)
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)
```

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.

```bash
# 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:

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

## Manual MCP setup

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

```json
{
  "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](https://pushary.com/docs?from=npm).

## 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](https://pushary.com/?from=npm)
- Docs: [pushary.com/docs](https://pushary.com/docs?from=npm)
- Sign up: [pushary.com/sign-up](https://pushary.com/sign-up?from=npm)
- Troubleshooting: [pushary.com/docs/agents/reference/troubleshooting](https://pushary.com/docs/agents/reference/troubleshooting?from=npm)
- Support and bug reports: [Discord](https://discord.gg/9v3VvUByrr) or [business@pushary.com](mailto:business@pushary.com)

## License

MIT