ping-a-human

Out-of-band

Reaches the human on Telegram, not inside the AI client UI — so it works even when nobody is watching the session.

Blocking ask

ask_human sends a question and waits for the reply, a tapped button, or a clean timeout. The agent gets a real answer.

One-command setup

A wizard validates your bot token, auto-detects your chat, writes the config, and prints the client snippet. No copy-paste guesswork.

Channels

Reach people where they already are.

Every channel sits behind one pluggable interface, so the tools never change. Telegram ships today — more are on the way.

Two tools

A small surface, fully wired.

`notify_human`

Fire-and-forget. Sends a message and returns immediately — perfect for “deploy finished” pings.

notify_human({ message: "Deploy to prod finished ✅" })

in · { message: string }

`ask_human`

Sends a question and blocks until the human replies, taps a choice, or the timeout elapses — returning a clean result either way.

ask_human({
  question: "Apply this migration to prod?",
  choices: ["Yes", "No"]
})

in · { question, choices?, timeoutMs? }

Quickstart

From npm to a working ask in minutes.

Run the setup wizard, paste the snippet into your MCP client, and your agent can reach you.

Full quickstart →

Create & configure

npx ping-a-human setup

Add to your MCP client

{
  "mcpServers": {
    "ping-a-human": {
      "command": "npx",
      "args": ["-y", "ping-a-human"]
    }
  }
}

Ask away

The client lists notify_human and ask_human. Done.

Docs MCP

Your agent reads its own docs.

Add the companion docs server and any AI agent can look up how to install, configure, and use ping-a-human — without you pasting docs into the prompt. Ask it “how do I set this up?” and it answers from the source.

search_docs — find the right page by question
get_doc — read a full page
list_docs — see everything that's documented

Browse the docs →

Add it to your MCP client

{
  "mcpServers": {
    "ping-a-human-docs": {
      "command": "npx",
      "args": ["-y", "ping-a-human-docs-mcp"]
    }
  }
}

Tip: add both servers and your agent can use ping-a-human and learn ping-a-human in the same session.

Pi coding agent

Human-in-the-loop for pi, in one command.

Pi is a terminal coding agent. ping-a-human-pi wires it into ping-a-human — so pi pings you when a task finishes and asks before risky commands. No MCP config, no glue code.

notify_human + ask_human — as native pi tools
Telegram ping on task completion — via pi's hooks
approval prompts before risky tool calls — opt-in
/ping in pi and a global pah CLI

Read the pi guide →

Install everything

npx ping-a-human-pi

Then run /reload in pi. Try it from the terminal: pah ping "hello".