pushary 1.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pushary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,330 @@
+# Pushary
+
+[![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 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, Hermes, and fx.
+
+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
+
+Run setup:
+
+```bash
+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:
+
+```bash
+npx @pushary/agent-hooks@latest setup --key pk_xxx.sk_xxx --skip-phone
+```
+
+Verify it worked:
+
+```bash
+npx @pushary/agent-hooks@latest doctor
+```
+
+Setup installs this package globally with npm, at the version you ran, because the
+hooks run from that install. You never install it by hand.
+
+## Remove it
+
+```bash
+npx @pushary/agent-hooks@latest clean
+```
+
+It removes the hooks, the MCP entries, the stored key and the background service.
+Add `--dry-run` to see what it would remove first.
+
+## 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 |
+| fx | yes | yes | no |
+
+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](https://pushary.com/pricing).
+
+Service lifecycle is explicit and cross-platform:
+
+```bash
+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
+
+<!-- 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. -->
+
+```
+cowork       Set up Claude Desktop and Cowork with the Pushary connector
+setup        Configure Claude Code, Codex, Gemini CLI, Hermes, Cursor, VS Code, OpenCode, or fx 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.
+
+```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
+```
+
+## 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:
+
+```bash
+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:
+
+```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
+
+## 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.