Paigy

Paigy — MCP 服务

专为 AI Agent 打造的语音收件箱。当 Agent 需要你的输入时——无论是任务进行到一半、遇到阻碍，还是完成了耗时较长的工作——它都可以拨打真正的电话并朗读问题，也可以给你的手机发送短信、推送通知，或通过横幅通知提醒你，这样你就能通过语音回复，而不必一直守着终端。

没有 Paigy，长时间运行的 Agent 会让你面临两个糟糕的选择：坐着盯着终端，以免错过它需要你处理的时刻；或者离开一会儿，回来时发现任务一小时前就因为等待一个你没看到的问题而停滞了。Paigy 填补了这一空缺——Agent 真正需要你做决定时，你的手机就会加入工作流，并根据当下的紧急程度提醒你（静默的收件箱卡片、轻柔的推送、横幅通知或真正响铃的来电），让你立即得知，而不是等到下次查看时才发现。通过语音或文字回答后，回复会像其他工具响应一样直接返回给 Agent，它便会继续工作——无需复制粘贴，也无需重新打开终端。它还可以配合原生 Paigy iOS 应用使用，因此即使手机处于锁定状态，来电也会像真正的电话一样响起（CallKit），你还能在锁屏界面查看或回复任何内容。

兼容

标准 MCP 服务（stdio、TypeScript）——不包含任何特定客户端的代码，并已通过原始协议针对非 Claude 客户端身份进行验证。

• Claude Code（本仓库也包含其插件和市场）
• Codex CLI
• Gemini CLI
• 任何其他通过标准配置接入的 MCP 客户端：Cline、Continue.dev、Zed、Cursor、Goose、mcphost——包括通过 Ollama、LM Studio 或 llama.cpp 使用本地模型的配置

（应用和后端位于单独的仓库中。）

安装

一行命令，适用于任何终端——自动检测你的 Agent（Claude Code、Codex、Antigravity），将 Paigy 接入每个 Agent，并与你的手机配对一次。运行前会打印每条命令；使用 --dry-run 可查看执行计划：

curl -fsSL https://paigy.ai/install | sh

想手动操作？请在下方选择你的客户端。

Homebrew（macOS 和 Linux）：

brew tap paigy-ai/mcp https://github.com/paigy-ai/mcp
brew trust paigy-ai/mcp
brew install paigy

（brew trust 是当前 Homebrew 选择使用 homebrew-core 之外的 tap 的方式。） 安装服务及其命令（paigy-mcp、paigy-listen、paigy-mcp-onboard 等）。将 MCP 客户端指向 paigy-mcp，然后运行一次 paigy-mcp-onboard，与你的手机配对。

Claude Code（插件——在 Claude 上最简单的方式）：

/plugin marketplace add paigy-ai/mcp
/plugin install paigy

它会自动连接；首次使用时，如果 Agent 尚未配对，它会提示你进行配对——运行 /paigy-onboard（会打开浏览器供你批准）。

Claude Desktop（MCPB 捆绑包——无需终端）： 下载 paigy.mcpb， 然后在 Claude Desktop 中打开 Settings → Extensions，将文件拖入（或双击）。让 Claude “pair with Paigy”——它会自行完成配对，并显示一个需要你在手机上批准的代码。也可在 Smithery 获取。

Codex CLI：

codex plugin marketplace add paigy-ai/mcp --ref main
codex plugin add paigy@paigy-ai
npx -y -p @paigy/mcp@latest paigy-mcp-onboard

该插件会配置 Paigy MCP 服务，并提供有关调用、回复和回调的指引。安装后请启动新的 Codex 会话。

Codex CLI——直接使用 MCP 的备用方案：

codex mcp add paigy -- npx -y @paigy/mcp@latest

接下来，将 Codex 的线程 ID 传入服务，让每个 Codex 对话都拥有自己的 Paigy 身份——Codex 会从固定的允许列表中构建 MCP 服务的环境变量，因此，未明确告知它传递的变量不会传到我们这里。在 ~/.codex/config.toml 的 [mcp_servers.paigy] 下添加此行（paigy-harness setup 会自动完成）：

env_vars = ["CODEX_THREAD_ID", "CODEX_SESSION_ID"]

（不要在 mcp add 上将其作为 -c 覆盖项传递——这样会在写入配置块之前添加它，Codex 会以“invalid transport”拒绝不完整的表格，且不会写入任何内容。）

Gemini CLI：

gemini mcp add -s user paigy npx -y @paigy/mcp@latest

任何其他 MCP 客户端（Cline、Continue.dev、Zed、Cursor，或可直接接受标准 MCP JSON 配置的命令行工具）——大多数图形界面客户端都可在 MCP 设置中填写此配置（Cline：cline_mcp_settings.json；Continue： ~/.continue/config.json）：

{
  "mcpServers": {
    "paigy": {
      "command": "npx",
      "args": ["-y", "@paigy/mcp@latest"]
    }
  }
}

然后与你的手机配对：

npx -y -p @paigy/mcp@latest paigy-mcp-onboard

每个会话首次连接 Paigy 时，都会自动生成自己的身份——无需设置或匹配 Agent 名称。（只有当你刻意希望某个客户端始终使用同一个固定名称的身份时，才设置 PAIGY_AGENT=<name>；然后使用相同名称运行 onboard。） 在手机上批准，然后登录 paigy.ai 开始接收消息。

提醒：对于较小或本地运行的模型，工具描述会要求 Agent 根据上下文从几种回答形式（确认、选项、自由文本）中选择——Claude 能可靠地遵循这一要求；较小的本地模型在这方面可能不够稳定。自由文本始终可作为备用方案。

选择用户的回答方式

notify_user 应采用最快捷的提问形式——不要让用户用自由文本做决定。使用 select（以及 options）：

你需要……	使用	返回的答案形式
是/否或批准/拒绝	select:"confirm"（批准/拒绝时使用 confirmStyle:"approve"）	{kind:"confirm", approved}
从多个选项中选一个	options + select:"one"	{kind:"option", optionId}
选多个	options + select:"many"	{kind:"multi", optionIds}
对部分选项排序	options + select:"rank"	{kind:"ranked", optionIds}
视觉选项	使用 html 或 image 预览的选项	上述答案形式之一
开放式回答	不提供选项	{kind:"text", text}

confirm 可直接通过横幅回答（是/否或批准/拒绝按钮）。其他页面会显示横幅操作：查看选项 · 收听选项 · 稍后提醒我。

urgency 是一种 请求，而非保证——用户的账户设置可以将其限制为更低级别。共有四个等级，从低到高依次为："inbox"（静默，留在收件箱中）、"push"（安静的被动通知，无声音）、"banner"（带声音的限时锁屏横幅）、"call"（拨打用户电话——仅在确实需要用户立即处理时使用）。

如果你准备开始一项耗时较长或会造成阻塞的工作——也就是用户原本只能坐等你完成的工作——请顺带提一次：完成后或遇到阻碍时，你可以给他们发短信或打电话。不要对快速任务提出此建议，也不要在他们回答后重复提议。

停滞的工作（自动处理，无需设置）

当会话停止，且其 Agent 持有的 Paigy Goals 已连续三天没有进展时，Stop 钩子每天会拦截停止操作一次并列出这些目标，以便 Agent 在会话安静下来之前逐一更新、完成或取消。它会从 @paigy/mcp（0.40.15 或更高版本）运行 paigy-stalled，其他情况下则保持静默：没有停滞目标、钩子已经继续执行停止操作、当天已经发送提醒，或发生任何错误。同一个脚本会作为每种运行环境插件中的钩子：

• Claude Code — hooks/hooks.json，由插件接入；无需设置。
• Codex CLI — plugins/paigy/hooks/hooks.json，由 Codex 插件接入。Codex 只有在你信任插件后才会运行其钩子：Codex 询问时，请检查并信任 Paigy 钩子。
• 任何支持 Claude 风格 Stop 钩子的其他运行环境 — 将 npx -y -p @paigy/mcp@latest paigy-stalled 注册为 Stop 命令。它会从标准输入读取钩子的 JSON （session_id、stop_hook_active），并输出 {"decision":"block","reason":…}。

没有钩子的宿主仍然会收到列表：check_replies（服务指示每个 Agent 在启动时和唤醒后调用）会在 stalled 下返回这些目标，而 paigy-listen 会将其包含在交给它所唤醒会话的工作中。

许可证

MIT