Pigeon Skill | Agent Skills

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:

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 <project> "<subject>" "<body>" | bash "$MAIL" send "<project>" "<subject>" "<body>" | | pigeon send --urgent <project> "<subject>" "<body>" | bash "$MAIL" send --urgent "<project>" "<subject>" "<body>" | | pigeon send --attach <path> <project> "<subject>" "<body>" | bash "$MAIL" send --attach "<path>" "<project>" "<subject>" "<body>" | | pigeon reply <id> "<body>" | bash "$MAIL" reply <id> "<body>" | | pigeon reply --attach <path> <id> "<body>" | bash "$MAIL" reply --attach "<path>" <id> "<body>" | | pigeon broadcast "<subject>" "<body>" | bash "$MAIL" broadcast "<subject>" "<body>" | | pigeon search <keyword> | bash "$MAIL" search "<keyword>" | | 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 <old> <new> | bash "$MAIL" alias "<old>" "<new>" | | 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 <path> (repeatable). Paths are resolved to absolute and stored as references - files are not copied.

# 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

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

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 ~/.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:

{
  "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

# 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

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.

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 |

Agent Skills: Pigeon

Install this agent skill to your local

Skill Files