ping-a-human-pi

Human-in-the-loop and notifications for the pi coding agent, powered by ping-a-human.

Pi has no built-in MCP support, so this package embeds a tiny MCP client and connects pi's hooks to ping-a-human. You get:

• notify_human / ask_human as native pi tools the model can call directly.
• Notifications — a Telegram ping every time pi finishes a task.
• Approval — pi asks you for the green light before risky tool calls (e.g. rm -rf, sudo, git push --force) and blocks them unless you say yes.
• /ping command — manually send yourself a notification: /ping or /ping your message here.
• pah CLI — a global terminal command, independent of pi: pah ping "build done", pah ask "deploy?".

Install

One command:

npx ping-a-human-pi

That's it. It:

• installs the pi extension into ~/.pi/agent/extensions/ping-a-human-pi/ (pi auto-discovers it),
• installs the pah CLI onto your PATH,
• seeds ~/.pi/agent/ping-a-human.json with sensible defaults (never overwrites an existing one).

Run /reload in pi (or restart it). To remove everything: npx ping-a-human-pi uninstall.

First time with ping-a-human? Configure Telegram once: npx ping-a-human setup.

pah CLI

A standalone command (no pi required) for pinging a human from any terminal:

pah ping "build finished"      # fire-and-forget notification
pah notify "deploy started"    # alias for ping
pah ask "ship to prod?"        # waits and prints the human's reply
pah --version                  # CLI version + the ping-a-human server version
pah help

It reads the same ~/.pi/agent/ping-a-human.json for the server command/args/env (defaults to npx -y ping-a-human). The installer drops it in the first writable PATH dir among ~/bin, ~/.local/bin, /usr/local/bin; if none are on PATH it creates ~/.local/bin and tells you to add it.

Alternatives:

npm i -g ping-a-human-pi        # global install of the pah CLI + installer
pi install npm:ping-a-human-pi  # load as a pi package
sh install.sh                   # from a cloned checkout

Configuration

All optional. Edit ~/.pi/agent/ping-a-human.json (see ping-a-human-pi.example.json):

Key	Default	Meaning
command / args	npx -y ping-a-human	how to launch the server
exposeTools	true	register notify_human / ask_human as model-callable tools
notify.enabled	true	ping you when a task finishes
notify.template	✅ pi finished a task in {cwd}:\n\n{summary}	message text; {summary} {cwd} substituted
approval.enabled	false	ask before risky tool calls
approval.tools	["bash"]	which pi tools to gate
approval.patterns	dangerous-command regexes	only gate calls whose args match one; empty = gate all calls of those tools
approval.template	🔐 pi wants to run {tool}:\n\n{details}\n\nApprove? (reply yes/no)	prompt; {tool} {details} substituted

A reply matching yes/ok/approve/allow/sure/go/lgtm/... approves; anything else blocks the call (and the reason is sent back to the model).

Uninstall

rm -rf ~/.pi/agent/extensions/ping-a-human-pi
rm -f ~/.pi/agent/ping-a-human.json   # optional
rm -f ~/bin/pah ~/.local/bin/pah /usr/local/bin/pah 2>/dev/null  # the CLI