Pigeon 是用于 Claude Code 的跨会话消息工具（pmail），让运行在不同项目目录中的 Claude Code 会话可以互相发送和接收消息。所有消息存储在一个全局 SQLite 数据库 ~/.claude/pmail.db 中，首次初始化或发送时自动创建。
用途
Pigeon 主要用于会话间协作：当某个会话完成了其他会话依赖的工作、共享接口或 API 契约发生变化、共享分支被破坏或修复、或者需要另一个项目会话的输入时，可以发送消息通知对方。
主要能力
命令通过 MAIL 简写执行，即 bash "$HOME/.claude/pigeon/mail-db.sh"。命令路由支持：read（读取邮件，可指定 id）、thread（查看消息串但不标记已读）、send（发送，支持 --urgent 紧急和 --attach 附件）、reply（回复，支持 --attach）、broadcast（广播）、search（按关键词搜索）、status（状态）、unread（未读）、list（列表，可指定数量）、projects（列出项目）、clear（清理，可指定天数）、alias（重命名项目显示名）、purge（清除，支持 --all）、id（查看项目身份）、migrate（迁移旧 ID）、init（初始化）。当用户说 check mail、read mail、inbox、any mail?、any pmail? 时执行 read；说 send mail to X、send pmail to X、message X 时解析并执行 send。
项目身份
每个项目根据其 git 根提交（仓库的第一个提交）生成稳定的 6 字符哈希 ID，因此目录重命名、移动和克隆后 ID 不变，大小写不敏感文件系统不会冲突，同一仓库的每个克隆共享同一身份。非 git 目录回退为规范路径（pwd -P）的哈希。使用 pigeon id 查看项目名称和哈希；发送消息时可以用名称、哈希或路径寻址，它们都解析到同一个哈希 ID。每个项目哈希渲染为唯一的像素风 identicon（11x11 对称网格，使用 Unicode 半块字符），运行 identicon.sh 查看自己的，或用 pigeon projects 查看所有项目。
被动通知（钩子）
全局 PreToolUse 钩子在每次工具调用时检查 pmail（无冷却时间）。收件箱为空时静默；有邮件等待时打印一个 JSON 信封，Claude Code 将其 additionalContext 传递给模型。JSON 格式是必需的，因为 PreToolUse 的普通 stdout 只进入 Claude Code 调试日志，永远不会到达模型。Claude Code 将 additionalContext 限制为 10,000 字符，因此钩子会在约 9,000 字符处截断消息正文并指向 pigeon read。消息投递不会标记为已读。每个会话只被告知每条消息一次：信号文件 /tmp/pigeon_signal_<hash> 是每次发送都会触碰的时间戳，每个会话保留自己的标记 /tmp/pigeon_seen_<hash>_<session_id>，记录它最后看到的邮件 id。
共享收件箱（Worktree）
项目中的每个会话读取同一个收件箱，仓库的各个 worktree 属于同一项目。这使 lane 到协调者的汇报能够工作。Pigeon 保证安全：不会把你自己发的邮件交给你（每条消息存储发送者的会话 id，钩子和 read、count、unread、status 会跳过调用会话发送的邮件）；一个会话的查看不会对另一个会话隐藏邮件（按会话追踪投递）；读取仍然是共享的（pigeon read 为整个项目标记已读，在 worktree 中钩子页脚会提示只标记发给你自己的邮件，一次一条 pigeon read <id>，pigeon thread <id> 只显示不标记）。名称可能冲突：名称是目录 basename，两个仓库可能同名，Pigeon 会在 stderr 警告、列出候选哈希，并在其中包含发送者项目时使用它；用哈希发送可指定。
附件
使用 --attach <path>（可重复）发送文件引用。路径解析为绝对路径并存储为引用，不复制文件。收件人看到附件路径和文件大小，可直接用 Read 工具读取；如果文件在发送后被移动或删除，显示为 (missing)。
依赖与安装
依赖 sqlite3（macOS、多数 Linux 发行版和 Windows Git Bash 自带，无需安装）和 jq（钩子用它构建 JSON 信封；没有 jq 钩子保持静默，但 pigeon read 仍可用）。安装分两步：将 mail-db.sh 和 check-mail.sh 复制到 ~/.claude/pigeon/ 并加执行权限，然后在 ~/.claude/settings.json 中添加 PreToolUse 钩子配置（matcher 为 *，command 为 bash "$HOME/.claude/pigeon/check-mail.sh"，timeout 5）。如果已有 hooks 配置，需合并而不是替换。不安装钩子时 pigeon 仍可用，但需手动检查。
数据库结构
单个 SQLite 文件 ~/.claude/pmail.db，包含 messages 表（id、from_project、to_project、subject、body、timestamp、read、priority、thread_id、attachments、from_session）和 projects 表（hash、name、path、registered）。
限制
邮件通过全局 SQLite 数据库存储，需要 sqlite3 可用；钩子通知需要 jq 才能以 JSON 形式到达模型。名称基于目录 basename，可能冲突，需要按哈希发送。读取为项目级共享，在 worktree 中需要按 id 逐条标记。每个会话发送的邮件不会投递给该会话自身。具体收费、价格、平台支持范围等资料未提供。
卸载
删除 ~/.claude/pigeon 和 ~/.claude/pmail.db，然后从 ~/.claude/settings.json 移除 hooks.PreToolUse 条目。