CLI & SDK

Your agent works, hits a decision, and asks your phone. You tap a button (or type a reply), and the answer lands back in the live session, so the agent keeps going.

@hwip/cli is the terminal side of that round trip:

• HwipHook SDK — native fetch, no runtime dependencies. Send, list, and dismiss pushes.
• hwip CLI — one-command setup for 10 agents, push sending, and a resident listener that lets the Hwip app type into the agent sessions you start through hwip (16 agents supported).

Quick start

Install the CLI globally, then run setup:

npm install -g @hwip/cli
hwip install

hwip install opens a browser sign-in on a fresh machine. The web app issues an API key and a hook as a matched pair, and the CLI writes them to ~/.hwip/config.json. No copy-paste. It then installs rules, hooks, and MCP for each detected agent.

Re-running is safe: a saved login is reused untouched, so a re-run just refreshes the agent integrations. To switch accounts, hwip install --relogin forces a fresh sign-in.

You also need the Hwip app signed in to the same account. A push or question needs an app to read it: with no app signed in, hwip notify and hwip ask send nothing and say so. See Getting started for the phone side.

Why global instead of npx

hwip cc, which lets the app drive a session, needs hwip on your PATH, and the agent hooks this installs resolve as $(command -v hwip || npx …). A global binary skips an npx cold start on every notification.

For notifications only, with no phone control, npx @hwip/cli install is a lighter alternative that skips the global binary (and with it hwip cc).

Install variants

# Headless box with no browser: paste credentials from another machine's ~/.hwip/config.json
hwip install --key ak_... --hook hook_...

# Skip the interactive agent picker
hwip install --only claude,cursor

# Switch account — force a fresh browser sign-in over a saved login
hwip install --relogin

# Refresh credentials only, without re-installing agents. This assumes you already ran
# `hwip install` once; on its own it does NOT wire MCP into agents.
hwip login

Send your first push

hwip notify --title "Deploy done" --body "v2.1.0 shipped"

What happens after install

The hooks fire in every session of each configured agent. hwip cc is the phone-control bridge, not the notification switch.

In Claude Code the routine per-turn push starts off — quiet is the default. While you are away from the terminal, a finished turn still pushes. /hwip-mode normal turns the routine push on for a project, /hwip-mode loud pushes on every turn, /hwip-mode mute silences a project entirely, and /hwip-mode shows what is in effect. See Mute and push mode.

~/.hwip/config.json is the single source of truth: the CLI, the MCP server, the plugin hooks, and the listener all read it. You never need HWIP_API_KEY-style environment variables for a normal setup; they exist as overrides for a second account or CI.

Supported agents

hwip install detects and configures these automatically:

Per-agent setup pages: Claude Code, Codex, Gemini CLI, pi, OpenCode.

Remote control via hwip listener covers a wider set: 16 agents that can run inside a named tmux session through the hwip <agent> wrapper. hwip install wires MCP, rules, or hooks for only the ten above, so the other wrapped agents (Kimi, Grok, Antigravity, Qwen, Auggie, Kilo, Kiro, Droid, Hermes, and Cursor's terminal agent) are reachable from the app and nothing more. See Remote control.

Requirements

• Node.js 20.17+, 22.13+, or 23.5+ (uses native fetch).
• tmux — required for hwip cc / codex / gemini and the other wrappers, and for hwip listener. hwip install checks for it and, on macOS with Homebrew, offers to run brew install tmux. tmux has no Windows build, so Windows needs WSL.
• The HwipHook SDK has no runtime dependencies. The CLI's dependencies include @inquirer/prompts for the interactive hwip install picker, ws for the listener's WebSocket subscription, and jsonc-parser to edit agent settings that hold comments.