Plugin submission: message-queue for rate-limit recovery across messaging channels

Plugin: message-queue

Author: Femi Odunaiya (@0xNagato)
Repository: https://github.com/0xNagato/claude-code/tree/feat/message-queue-plugin
PR in fork: https://github.com/0xNagato/claude-code/pull/1

Summary

Adds a new plugin that provides idempotent message queuing with automatic rate-limit recovery across all messaging channels (iMessage, WhatsApp, Telegram, Signal, Discord, Slack).

Problem

When messaging APIs return rate-limit errors (429, retry-after headers, quota exceeded), messages are lost or require manual retry. This is especially painful for automated agents that need to respond to incoming messages reliably.

Solution

This plugin provides:

1. Idempotent enqueue - Messages are deduplicated by content hash (SHA-256), so retries never create duplicates
2. Optimistic locking - UUID-based locks with TTL prevent double-sends when concurrent processors (heartbeat + cron) race
3. Automatic retry scheduling - Parses Retry-After headers, X-Rate-Limit-Reset, and common error patterns; schedules cron wake events for exact retry times
4. Channel-agnostic - Works with iMessage, WhatsApp, Telegram, Signal, Discord, Slack via channel-specific send methods
5. Graceful degradation - Max 5 retries with exponential backoff, then marks dead_letter for manual review
6. Heartbeat fallback - Safety net that processes any stale pending messages whose rate-limit window has passed

Tools exposed

| Tool | Purpose |
|------|---------|
| mq_enqueue | Idempotently queue a rate-limited message |
| mq_process | Lock and process ready messages (concurrency-safe) |
| mq_ack | Mark sent or requeue with new retry window |
| mq_status | Queue health: counts, next retry time, oldest pending |

Files added

• plugins/message-queue/.claude-plugin/plugin.json - Plugin manifest
• plugins/message-queue/README.md - Documentation
• plugins/message-queue/index.py - Core implementation (562 lines)
• plugins/message-queue/test_message_queue.py - 35 passing tests covering state transitions, dedup, locking, lock expiry recovery, retry exhaustion, pruning, and rate-limit error pattern parsing

Testing

All 35 tests pass:

Conforms to existing plugin patterns

• Structure matches plugins/code-review/, plugins/hookify/, etc.
• Uses plugin.json manifest with name, version, description, author, homepage
• Pure Python, no external dependencies beyond stdlib
• Entry point via index.py with TOOLS dict export

---

Since the upstream repo restricts PR creation to collaborators, please create the PR from this fork's branch: → .