Paigy is an MCP (Model Context Protocol) server positioned as a voice inbox for AI agents. Its core goal is to solve the problem in long-running agent sessions where the user must stay by the terminal the whole time, otherwise they may miss the agent's question and cause the task to stall. When the agent genuinely needs the user to make a decision, Paigy pulls the user's phone into the loop with an urgency level matching the current situation.
[Main Capabilities] Paigy supports multiple ways to contact the user, divided into four levels of urgency from low to high: "inbox" (silent, stays in the inbox), "push" (a quiet, soundless passive notification), "banner" (a time-sensitive lock-screen banner with sound), "call" (phone call to the mobile phone). urgency is a request rather than a guarantee, and the user's account settings can lower its ceiling. Users can reply by voice or text, and the reply is returned to the agent like any other tool response, whereupon the agent continues execution without copy-pasting or reopening the terminal. It also works with the native Paigy iOS app, which can ring like a real phone call even when the phone is locked (CallKit), and allows viewing or replying from the lock screen.
[How to Use] Paigy is a standard MCP server (based on stdio, TypeScript), contains no client-specific code, and has been verified over the raw protocol under a non-Claude client identity. It supports multiple ways to connect: Claude Code (this repository is both its plugin and its marketplace), as well as other MCP clients via standard configuration, including Cline, Continue.dev, Zed, Cursor, Goose, mcphost, and also local model environments based on Ollama, LM Studio, or llama.cpp. The project provides a one-line install command that works in any terminal, can automatically detect the user's agents (Claude Code, Codex, Antigravity), connects Paigy to each agent, and completes phone pairing once. All commands are printed before execution, and --dry-run can be used to view the plan. Users can also configure it manually.
The Claude Code plugin method is the simplest: it takes effect automatically after connecting, prompts the user to pair on first use if not yet paired, and running /paigy-onboard opens a browser for approval. Claude Desktop can be used via the MCPB packageInstalling without a terminal: after downloading paigy.mcpb, open Settings → Extensions in Claude Desktop and drag the file in (or double-click it). Then have Claude "pair with Paigy" to complete pairing and display a code to approve on your phone.
Each session automatically generates its own identity the first time it reaches Paigy; there is no need to set up or match an agent name. Only set PAIGY_AGENT=<name> if you deliberately want a given client to always speak under a fixed named identity, and run onboard with the same name. After approving on your phone, sign in to paigy.ai to start receiving messages.
[Response form selection] notify_user should ask the question in the fastest answerable form; do not leave the decision as free text. select (with options) can be used to let the user choose from options; confirm can be answered directly from the banner with Yes/No or Approve/Deny buttons; other paige will come with the banner actions "See Options · Hear them · Remind me later".
[Handling stalled tasks] When a session stops and its agent has Paigy Goals and there has been no progress for three consecutive days, a Stop hook will intercept the stop once a day and list those goals, so that the agent updates, completes, or cancels each one before going quiet. This feature is automatic and requires no configuration; it is run by @paigy/mcp (version 0.40.15 or later) running paigy-stalled. Otherwise it stays silent: when there are no stalled tasks, when the stop has already been continued by some hook, when a reminder has already been given that day, or on any error. Claude Code connects to hooks/hooks.json through a plugin, with no setup required; Codex CLI connects to plugins/paigy/hooks/hooks.json through the Codex plugin, and the Paigy hook must be reviewed and trusted first; other harnesses with a Claude-style Stop hook can register npx -y -p @paigy/mcp@latest paigy-stalled as the Stop command.
[Applicable scenarios and limitations] It is suitable for agent sessions that need mid-course user decisions, are blocked, or run for a long time, letting users avoid having to stay by the terminal. For smaller or local models, the tool descriptions require the agent to choose among several response forms (confirm, options, free text) based on the situation; Claude can follow this reliably, while smaller local models may be less consistent, and free text can always be used as a fallback. The app and backend are in separate repositories.
