Push Notifications & Agent Hooks
How It Works
rootshell-notify is a small command-line tool that sends push notifications
from any computer to rootshell. You can call it directly from scripts, cron jobs, CI,
builds, or deployments. Its optional Claude Code and Codex integrations call the same
tool from agent hooks when a turn finishes or needs your attention.
- rootshell creates a pairing bundle for one device.
- The setup command installs the CLI, pairs that device, sends a test, and adds hooks for supported agents it finds.
- A hook turns the agent event into a short notification and adds routing hints for the originating terminal pane.
- The sender encrypts the message before sending it through the stateless relay.
- Tap the notification to return to its rootshell window, tab, and pane, including tmux control-mode panes.
Install and Pair
In rootshell, open Settings → Notifications → Push Notifications → Pair a Computer. Copy the generated install command into the computer that will send notifications. Only the command created by the destination device can pair it.
The installer places rootshell-notify in ~/.local/bin, verifies
the downloaded binary, pairs the device, sends a test notification, and installs hooks
for Claude Code and Codex when it finds them. Re-running setup is safe and does not
duplicate hook entries.
| Installer option | What it does |
|---|---|
--pair <bundle> | Pairs after installation. |
--hooks auto | Installs hooks for every supported agent found. This is the default. |
--hooks claude-code,codex | Installs the named integrations. |
--hooks none | Installs the CLI without agent hooks. |
--project | Writes hooks to the current project instead of your user configuration. |
--system | Installs the binary in /usr/local/bin. |
If the CLI is already installed, pair and configure hooks directly:
rootshell-notify setup --pair 'rspair1....'
rootshell-notify setup --pair 'rspair1....' --hooks codex
rootshell-notify install claude-code
rootshell-notify install codex
Agent installation appends only rootshell-tagged entries, preserves existing settings,
and writes a backup the first time it changes a file. User hooks live in
~/.claude/settings.json and ~/.codex/hooks.json; use
--project for ./.claude or ./.codex instead.
After installing a Codex hook, open /hooks in Codex, review the rootshell
entry, and mark it trusted.
Agent Events
| Agent | Event | Notification status |
|---|---|---|
| Claude Code | A main-agent turn stops | Done |
| Claude Code | A permission prompt, question, elicitation, or other supported input request appears | Blocked |
| Claude Code | An idle or agent-completed notification arrives | Done |
| Codex | A main-agent turn stops | Done |
| Codex in rootshell | An approval prompt is visibly waiting in the terminal | Blocked, detected on device |
Subagent stops, re-entrant stop hooks, unsupported tool events, and unrelated notification types are ignored. Hooks never answer questions or approve actions. Codex permission events occur before review decides whether you must act, so the hook does not treat them as blocked; rootshell’s on-device detector handles a visible approval prompt instead.
What Leaves the Computer
Each supported agent notification can contain:
- A title identifying Claude Code or Codex and the project directory.
- Up to 200 characters from the last assistant message, or the relevant notification, question, or pending command.
- Routing hints such as the rootshell pane, tmux pane and session,
user@host, and working directory. - Hashed session and event identifiers for grouping and deduplication.
Prompts, terminal output, transcripts, files, and environment variables are never sent. Before encryption, summaries are stripped of code blocks, links, URLs, and recognizable credential patterns. Titles, summaries, and routing hints are encrypted on the sender with X-Wing (ML-KEM-768 + X25519); the stateless relay sees only ciphertext.
Send Your Own Notifications
rootshell-notify send --title "Deploy finished" --body "prod is green" --status done
rootshell-notify send --title "Build" --status failed --priority high --device "Desk iPad"
Manual send messages always show, even when automatic agent notifications are
disabled for a paired device. They are text-only and can include a title, body, status,
priority, destination device, and routing hints.
Manage Devices
rootshell-notify devices
rootshell-notify devices off "Desk iPad"
rootshell-notify devices on "Desk iPad"
rootshell-notify unpair "Desk iPad"
Each paired computer has a separate revocable credential. Turning a destination off only
suppresses automatic agent-hook notifications; tests and manual sends can still reach it.
Pairings are stored in ~/.config/rootshell-push/config.json with mode 0600.
Set ROOTSHELL_PUSH_CONFIG to use another path.
Upgrade or Remove
rootshell-notify upgrade
rootshell-notify upgrade --check
rootshell-notify uninstall claude-code
rootshell-notify uninstall codexAn upgrade verifies and replaces the binary, then refreshes installed hooks without changing pairings. Uninstall removes only rootshell’s tagged entries and preserves other hooks. Revoke the sender from rootshell’s Push Notifications settings when you no longer want that computer to send to the device.
Troubleshooting
- Run
rootshell-notify statusto check the binary, config, pairings, agent-notification state, hooks, and available updates. - Run
rootshell-notify testto send a test to every paired device. - Make sure
~/.local/binis on the PATH visible to the coding agent. - Hook errors go to
~/.config/rootshell-push/hook.logand never fail the agent. - If a device was reinstalled or re-registered and the relay returns 410, unpair it and create a new pairing from that device.