--- name: pigeon description: "Inter-session pmail - send and receive messages between Claude Code sessions running in different project directories. Uses global SQLite database at ~/.claude/pmail.db. Triggers on: mail, pmail, send message, check mail, inbox, inter-session, message another session, pigeon." license: MIT allowed-tools: "Read Bash Grep" metadata: author: claude-mods related-skills: sqlite-ops --- # Pigeon Inter-session messaging for Claude Code. Send and receive pmail between sessions running in different projects. ## Quick Reference All commands go through `MAIL`, a shorthand for `bash "$HOME/.claude/pigeon/mail-db.sh"`. Set this at the top of execution: ```bash MAIL="$HOME/.claude/pigeon/mail-db.sh" ``` Then use it for all commands below. ## Command Router Parse the user's input after `pigeon` (or `/pigeon`) and run the matching command: | User says | Run | |-----------|-----| | `pigeon read` | `bash "$MAIL" read` | | `pigeon read 42` | `bash "$MAIL" read 42` | | `pigeon send "" ""` | `bash "$MAIL" send "" "" ""` | | `pigeon send --urgent "" ""` | `bash "$MAIL" send --urgent "" "" ""` | | `pigeon send --attach "" ""` | `bash "$MAIL" send --attach "" "" "" ""` | | `pigeon reply ""` | `bash "$MAIL" reply ""` | | `pigeon reply --attach ""` | `bash "$MAIL" reply --attach "" ""` | | `pigeon broadcast "" ""` | `bash "$MAIL" broadcast "" ""` | | `pigeon search ` | `bash "$MAIL" search ""` | | `pigeon status` | `bash "$MAIL" status` | | `pigeon unread` | `bash "$MAIL" unread` | | `pigeon list` | `bash "$MAIL" list` | | `pigeon list 50` | `bash "$MAIL" list 50` | | `pigeon projects` | `bash "$MAIL" projects` | | `pigeon clear` | `bash "$MAIL" clear` | | `pigeon clear 7` | `bash "$MAIL" clear 7` | | `pigeon alias ` | `bash "$MAIL" alias "" ""` | | `pigeon purge` | `bash "$MAIL" purge` | | `pigeon purge --all` | `bash "$MAIL" purge --all` | | `pigeon id` | `bash "$MAIL" id` | | `pigeon migrate` | `bash "$MAIL" migrate` | | `pigeon init` | `bash "$MAIL" init` | When the user just says "check mail", "read mail", "inbox", "any mail?", or "any pmail?" - run `bash "$MAIL" read`. When the user says "send mail to X", "send pmail to X", or "message X" - parse out the project name, subject, and body, then run `bash "$MAIL" send`. ## Project Identity Each project gets a stable 6-character hash ID derived from its **git root commit** (the very first commit in the repo). This means: - IDs survive directory renames, moves, and clones - Case-insensitive filesystems (macOS) don't cause collisions - Every clone of the same repo shares the same identity For non-git directories, falls back to a hash of the canonical path (`pwd -P`). Use `pigeon id` to see your project's name and hash: ``` claude-mods 7663d6 ``` When sending messages, you can address projects by **name**, **hash**, or **path** - they all resolve to the same hash ID. ### Identicons Each project hash renders as a unique pixel-art identicon (11x11 symmetric grid using Unicode half-block characters). Run `identicon.sh` to see yours, or view all projects with `pigeon projects`. ## Passive Notification (Hook) A global PreToolUse hook checks for pmail on every tool call (no cooldown). Silent when inbox is empty. ``` === PMAIL: 3 unread message(s) === From: some-api | Auth endpoints ready From: frontend | Need updated types ... and 1 more Use pigeon read to read messages. ``` ## Attachments Send file references with `--attach ` (repeatable). Paths are resolved to absolute and stored as references - files are not copied. ```bash # Send with one attachment pigeon send --attach src/config.ts my-api "Config update" "Updated the auth config" # Send with multiple attachments pigeon send --attach src/schema.sql --attach docs/API.md my-api "Schema + docs" "See attached" # Reply with attachment pigeon reply --attach output/report.json 42 "Here's the analysis" ``` Recipients see attachment paths with file sizes and can read them directly with the Read tool. If a file has been moved or deleted since sending, it shows as `(missing)`. ## When to Send - You've completed work another session depends on - An API contract or shared interface changed - A shared branch (main) is broken or fixed - You need input from a session working on a different project ## Per-Project Disable ```bash touch .claude/pigeon.disable # Disable hook notifications rm .claude/pigeon.disable # Re-enable ``` Only the hook is disabled - you can still send messages from the project. --- ## Installation Pigeon requires two things: **scripts** (the mail engine) and a **hook** (passive notifications). Both install globally - one setup, every project gets pmail. ### Prerequisites - `sqlite3` - ships with macOS, most Linux distros, and Git Bash on Windows. No install needed. ### Step 1: Copy Scripts ```bash mkdir -p ~/.claude/pigeon cp skills/pigeon/scripts/mail-db.sh ~/.claude/pigeon/ cp hooks/check-mail.sh ~/.claude/pigeon/ chmod +x ~/.claude/pigeon/mail-db.sh ~/.claude/pigeon/check-mail.sh ``` This gives you the pmail commands. You can now send and read messages manually: ```bash bash ~/.claude/pigeon/mail-db.sh init # Create database bash ~/.claude/pigeon/mail-db.sh status # Check it works ``` ### Step 2: Enable the Hook Add a `hooks` block to `~/.claude/settings.json`. This makes Claude check for pmail automatically on every tool call: ```json { "hooks": { "PreToolUse": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "bash \"$HOME/.claude/pigeon/check-mail.sh\"", "timeout": 5 } ] } ] } } ``` **Important:** If you already have a `hooks` section in your settings, merge the PreToolUse entry into the existing array - don't replace the whole block. Without this step, pigeon still works but you have to check manually (`pigeon read`). With the hook, unread pmail appears automatically. ### What Gets Created ``` ~/.claude/ settings.json # Hook config (you edit this) pmail.db # Message store (auto-created on first use) pigeon/ mail-db.sh # All pmail commands (send, read, reply, etc.) check-mail.sh # PreToolUse hook (silent when inbox empty) ``` ### Verify ```bash # Check your project identity bash ~/.claude/pigeon/mail-db.sh id # Send yourself a test message (use your project name from above) bash ~/.claude/pigeon/mail-db.sh send "my-project" "Test" "Hello from pigeon" # Check it arrived bash ~/.claude/pigeon/mail-db.sh read # Clean up bash ~/.claude/pigeon/mail-db.sh purge --all ``` ### Uninstall ```bash rm -rf ~/.claude/pigeon ~/.claude/pmail.db # Then remove the hooks.PreToolUse entry from ~/.claude/settings.json ``` ## Database Single SQLite file at `~/.claude/pmail.db`. Auto-created on first `init` or `send`. ```sql CREATE TABLE messages ( id INTEGER PRIMARY KEY AUTOINCREMENT, from_project TEXT NOT NULL, -- 6-char hash ID to_project TEXT NOT NULL, -- 6-char hash ID subject TEXT DEFAULT '', body TEXT NOT NULL, timestamp TEXT DEFAULT (datetime('now')), read INTEGER DEFAULT 0, priority TEXT DEFAULT 'normal' ); CREATE TABLE projects ( hash TEXT PRIMARY KEY, -- 6-char ID (git root commit or path hash) name TEXT NOT NULL, -- Display name (basename of project dir) path TEXT NOT NULL, -- Canonical path registered TEXT DEFAULT (datetime('now')) ); ``` ## Troubleshooting | Issue | Fix | |-------|-----| | `sqlite3: not found` | Ships with macOS, Linux, and Git Bash on Windows. Run `sqlite3 --version` to check. | | Hook not firing | Ensure `hooks` block is in `~/.claude/settings.json` (Step 2 above) | | Hook fires but no notification | Working as intended - hook is silent when inbox is empty | | Messages not arriving | Target must be a known name, hash, or path. Use `pigeon projects` to see registered projects | | Upgraded from basename IDs | Run `pigeon migrate` to convert old messages to hash-based IDs | | Changed display name | Use `pigeon alias old-name new-name` to update the project's display name | | Want to disable for one project | `touch .claude/pigeon.disable` in that project's root | | Check your project ID | Run `pigeon id` to see name and 6-char hash |