Asigers / pi-knock

# pi-knock
English | 简体中文
**Leave the terminal. Pi will knock when it needs you.**
pi-knock is a Pi coding agent extension that sends remote notifications when a task **finishes, fails, or needs your input**. Use Pushover for iPhone / Apple Watch, ntfy for hosted or self-hosted push, or a webhook for your own automation.
## Why pi-knock?
Desktop notifications only help when you're near your computer. pi-knock lets you hand work to Pi and walk away: it sends the important moments to your phone or watch.
- **Know when Pi is actually done** — completion alerts fire after Pi has settled, including automatic retries and queued work.
- **Come back only when Pi needs you** — get notified when input or confirmation is required.
- **Stay away from the terminal** — receive alerts through Pushover, ntfy, or your own webhook automation.
## Contents
- Why pi-knock?
- Features
- Quick start
- Commands
- Providers
- Notification behavior
- Configuration
- Update and uninstall
- Development
- Documentation
- License
## Features
- **Actually waits for completion** — completion alerts are sent at `agent_settled`, after Pi has finished automatic retries and queued work.
- **Works away from your desk** — notifications can reach your phone or watch instead of only the local terminal.
- **Reliable delivery** — transient failures are retried automatically.
- **Lock-screen safe by default** — prompt text is hidden unless you opt in.
- **Session-aware** — named Pi sessions appear in notification titles.
- **No push server required** — pi-knock sends directly to your configured provider.
## Quick start
**Requirements:** Pi 0.87+ and Node.js 22.19+.
### 1. Install
The recommended installation is npm:
 [code] 
Choose **one** installation source. Do not install both npm and Git versions at the same time, or Pi may load the extension twice and send duplicate notifications.
For development or unreleased source only, use the tagged Git version instead:
 [code] 
If you are unsure which copy is installed, run `pi list` and keep only one `pi-knock` entry.
### 2. Configure
Restart Pi or run `/reload`, then launch the setup wizard:
 [code] 
Choose a provider and enter the required settings. Saving a provider configuration immediately sends a test notification.
> **Credential privacy:** Pi's standard input is not masked. Enter credentials only in a private terminal or session.
### 3. Verify
Send another test notification whenever you need to check delivery:
 [code] 
If it does not arrive, run `/knock doctor` to inspect the provider configuration and last delivery result.
## Commands
Run these commands inside Pi:
| Command | Description |
| --- | --- |
| `/knock setup` | Configure providers and notification preferences |
| `/knock status` | Show current configuration |
| `/knock test` | Send a live test notification |
| `/knock doctor` | Show provider and last-delivery diagnostics |
## Providers
| Provider | Best for |
| --- | --- |
| **Pushover** | iPhone / Apple Watch |
| **ntfy** |