Command Reference

# Send a notification
hwip notify --title "Deploy done" --body "v2.1.0 shipped"

# Send with priority
hwip notify --title "Build failed" --priority high --url https://ci.example.com/123

# Send to a channel you own
hwip channel list
hwip notify --channel Releases --title "v2.1.0" --body "shipped"

# List recent pushes
hwip list
hwip list --limit 10 --type note

# Dismiss a push
hwip dismiss push_01JXY...
hwip dismiss --all

# Rename the current agent session (shows in the app's Agents list)
hwip rename "Prod deploy"
hwip rename --clear                # reset to the default name

# Type a message into another agent session, here or on another computer
hwip agent send dev_listener_ab12cd34:hwip-api "Build is green — rerun the e2e suite"
hwip agent send hwip-api "…"       # a name or alias works when it names one session

# See which agent sessions run on THIS computer, and what one did last
hwip agent list                    # KEY  AGENT  STATE  NAME; --json for scripts
hwip agent read hwip-api           # its last 3 turns: prompt, the agent's text, tool names

# Drop an ended session from this machine's record
hwip forget --ended

# Test connection
hwip test

# Run an agent in a named tmux session, so the listener can reach it
hwip cc                       # claude
hwip codex                    # codex
hwip gemini                   # gemini
hwip pi                       # pi
hwip opencode                 # opencode
hwip cc --wt feat/x           # claude in a new git worktree + branch

# Start an agent session on a timer (the listener starts it)
hwip schedule add cc --at 09:00 --days weekdays --prompt "Triage the open issues"
hwip schedule

# Run the resident listener (foreground; background it as you like)
hwip listener
hwip listener --ws-url wss://...   # override config

# JSON output
hwip notify --title "Hello" --json

Commands

Notify options

The defaults are tuned for hook-driven invocations, for example a Stop hook calling hwip notify --title "Task done" with no body. You see which project and branch finished without writing per-IDE wrappers. Pass --body "" explicitly to suppress it.

Listener options

The listener reconnects with exponential backoff plus jitter, from 1 second to a 30-second cap. On an authentication failure close (4001, 4002, 4003) it exits with code 3 instead of looping forever: fix the key and restart.

List options

Global options

A flag that takes a value takes the next word whatever it looks like, so text nobody typed (a command to approve, a model's message) cannot set a flag of hwip's. -- ends hwip's flags. After an agent subcommand such as hwip cc, the words go to the agent untouched.

Mute and push mode

Both live as state files under ${XDG_STATE_HOME:-~/.local/state}/hwip, keyed by a cksum hash of the project directory. Claude Code's /hwip-mode mute, /hwip-mode quiet, /hwip-mode loud, and /hwip-mode normal write them; the CLI reads them: mute on every notify, push mode on --auto.

Notifications are silently skipped when a mute file exists for the current project:

STATE_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/hwip"
HASH=$(printf '%s' "$PROJECT_DIR" | cksum | cut -d' ' -f1)

# Mute (created by /hwip-mode mute in the Claude Code plugin)
mkdir -p "$STATE_DIR" && touch "$STATE_DIR/muted-$HASH"

# Unmute
rm -f "$STATE_DIR/muted-$HASH"

Push mode is a one-word file (quiet, loud, or normal) resolved in this order, first hit wins:

Row 4 sits below the state files on purpose: the flag names a default, it does not override a dial you set. A dial file that exists but reads empty resolves to normal, not to row 5.

Mute has no -default form on purpose: it is keyed on presence, not content, so a global mute could never be lifted for a single project.

Quiet while away

quiet silences routine pushes because you are watching the pane. When you have walked away, notify --auto under quiet still sends the push (normal priority). It decides you are away when no tmux client is attached, or when input has been idle longer than HWIP_AWAY_SEC seconds (default 300; 0 turns detection off). Anything it cannot read counts as present.

The CLI checks CLAUDE_PROJECT_DIR, CURSOR_PROJECT_DIR, and WINDSURF_PROJECT_DIR, and falls back to the cwd.

Last push failure

Installed hooks run hwip notify … 2>/dev/null || true, so a failed push leaves nothing on screen. hwip notify, hwip test, and the test push hwip install sends therefore record the last failure in ${XDG_STATE_HOME:-~/.local/state}/hwip/last-notify-failure.json and delete it once a push goes through. kind is one of no-key, auth, quota, rate-limit, client, server, timeout, network, no-app, unsealed. No message text, key or push content is stored. hwip verify shows it under Push delivery.

Exit codes

Environment variables