A carrier between
agents and you.

Pidgin's hosted web UI runs at pidginroost.com, and the hosted API runs at api.pidginroost.com. There's nothing to deploy on your side.

Confirm the server is healthy

curl -sf https://api.pidginroost.com/health | jq .
# → {"ok":true,"data":{"status":"healthy"}}

If that returns ok: true, you're set — continue to Apps.

The native apps receive push notifications, display messages, and let you reply. iOS and macOS share a single XcodeGen project at clients/apple.

Install via Xcode

You'll need Xcode 16+ and an Apple Developer account with a connected device.

Generate the project

cd pidgin/clients/apple   # from your repo clone
brew install xcodegen   # if needed
xcodegen generate
open Pidgin.xcodeproj

Run on iPhone

• Select the Pidgin-iOS scheme and your connected iPhone as destination
• Press Run (⌘R)
• Trust the developer certificate: Settings → General → VPN & Device Management

Run the macOS app

• Switch scheme to Pidgin-macOS and press Run (⌘R)

Each app logs in with a magic link, then registers its APNs device token so the server knows where to push.

iOS app

• Open the Pidgin iOS app and enter your email (must be an active invited member — Pidgin is members-only)
• Use https://pidginroost.com/onboarding from the app's setup guide link if you need the browser walkthrough
• Tap Send magic link — check your email
• Tap the link (or paste it in Safari if universal links aren't working yet) to complete login
• Allow notifications when prompted — device token is registered automatically

macOS app

• Same magic link flow as iOS
• Allow notifications in System Settings → Notifications if you missed the prompt

Confirm device registration

Use your Pidgin API key. On macOS, the CLI script can read the key that the app stored in the login keychain; otherwise export it manually.

export PIDGIN_API_KEY="your-api-key"
curl -s https://api.pidginroost.com/api/registry \
  -H "Authorization: Bearer $PIDGIN_API_KEY" | jq '.data[]'

You should see your device listed with a recent registered_at timestamp.

Codex and shell agents use the checked-in script directly. Claude Code can also install the plugin commands. Either path can send push notifications mid-task and poll for your reply before continuing.

Step 1 — Check local credentials

The script defaults to the hosted API. On macOS it reads the key saved by the signed-in Pidgin app; on other systems, set the key manually:

export PIDGIN_URL="https://api.pidginroost.com"
export PIDGIN_API_KEY="your-api-key-here"

bash ~/ashcode/pidgin/scripts/pidgin.sh check

Step 2 — Use it from Codex or shell agents

Codex and other terminal agents can call the script directly from this repo:

bash ~/ashcode/pidgin/scripts/pidgin.sh send \
  --type message \
  --title "Codex is connected" \
  --body "Pidgin is available from this Codex workflow." \
  --project "codex"

For durable Codex workflows, make the script path and any required env vars available to the shell or task runner that launches Codex.

Step 3 — Optional Claude Code plugin

In a Claude Code session, add the marketplace and then install the plugin — adding a marketplace alone doesn't install anything:

/plugin marketplace add ashrocket/pidgin
/plugin install pidgin@pidgin

Or, if you've cloned the repo locally:

/plugin marketplace add /path/to/your/pidgin
/plugin install pidgin@pidgin

The argument is <plugin>@<marketplace> — both are named pidgin here. Trust the plugin when prompted. This registers the following commands:

Step 4 — Verify Claude Code

/pidgin-setup

This checks env vars, curl/jq, server connectivity, and sends a test push. Watch for the notification — if it arrives, you're done.

Natural language triggers

The Pidgin skill activates automatically when you say:

• "Pidgin it to me" — send the last output as a push
• "Send it to my phone" or "notify me" — push notification
• "Email it to me" — Gmail draft if Gmail MCP is connected, otherwise push
• "Ask me when you get to the auth step" — Claude pauses and sends a question mid-task
• "Text me" — iMessage if available, push as fallback

You can still reach Pidgin from Claude Desktop by wiring env vars into your MCP server config. Claude Desktop doesn't inherit ~/.zshrc, so add them explicitly in ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "your-existing-server": {
      "command": "...",
      "args": [...],
      "env": {
        "PIDGIN_URL": "https://api.pidginroost.com",
        "PIDGIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

For document workflows, Claude Desktop can also use the remote MCP endpoint at https://pidginroost.com/mcp if your MCP client supports remote OAuth. The current MCP tools cover document list, search, retrieval, publishing, and share-link generation. Push notifications still use the Claude Code plugin or the REST script.

Pidgin exposes a remote MCP endpoint for document workflows and a browser UI for clients that do not have a native Pidgin plugin.

Remote MCP

https://pidginroost.com/mcp

The Worker publishes OAuth metadata for remote clients:

https://pidginroost.com/.well-known/oauth-protected-resource/mcp
https://pidginroost.com/.well-known/oauth-authorization-server

• ChatGPT — add the remote MCP server URL if the workspace supports custom remote MCP connectors, then complete the Pidgin OAuth login.
• Claude Desktop / Claude Design-style work — use the remote MCP URL for document tools, or keep using Claude Code for push notifications and reply polling.
• Codex — use scripts/pidgin.sh for push/reply workflows and the MCP endpoint when the environment supports remote MCP.
• Perplexity and browser agents — use the browser UI and public/share links today; use the same MCP URL if the client supports remote MCP + OAuth.

Browser fallback

Any browser-capable agent can use the web UI:

https://pidginroost.com
https://pidginroost.com/onboarding
https://pidginroost.com/setup

Use the browser path for login, setup, reading documents, generating share links, and checking the inbox when a tool client cannot call the REST API or MCP endpoint directly.

Run this end-to-end check from a terminal. It should produce a push on your phone within a few seconds.

export PIDGIN_URL="${PIDGIN_URL:-https://api.pidginroost.com}"

curl -X POST "$PIDGIN_URL/api/messages" \
  -H "Authorization: Bearer $PIDGIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "question",
    "title": "Pidgin setup complete",
    "body": "Reply with ok to confirm the connection works.",
    "priority": "normal",
    "instance": {
      "model": "manual-test",
      "session_id": "setup-check",
      "project": "pidgin-onboarding",
      "source": "curl"
    }
  }'

Common issues