Other frameworks

Pidge is deliberately SDK-free: if your framework can run a shell command or make an HTTP call, it can integrate. The surface is always the same two directions:

agent ──(send)──▶ Pidge                 Pidge ──(replies)──▶ agent
  POST /api/v1/notify                     poll · long-poll · webhook · GET /api/v1/messages

hermes-agent — the official plugin

pidge-sh/hermes-pidge (public, MIT) makes Pidge a full hermes-agent gateway platform — a Telegram replacement with OS-level delivery. Three-command install; highlights:

• No inbound endpoint needed. A single long-poll loop on GET /api/v1/messages?wait=25&all=true consumes both composer messages and notification replies (at-least-once ack) — it runs from behind NAT.
• Exec approvals and clarify prompts render as real notification actions (including Face ID-gated ones).
• The bundled pidge LLM tool adds rich sends, blocking waits, Live Activities and create_channel — minting a sibling key so each subagent gets its own identity instead of sharing one.
• reply_to webhooks remain available as an optional passthrough for external systems.

Any other framework

Pick the receive path that matches your shape:

Your agent is…	Send with	Receive with
a CLI / turn-based session	npx pidge-cli	ask/wait (blocking) or listen
a long-running process, no public URL	POST /api/v1/notify	long-poll GET /api/v1/messages?wait=25 + ack
a service with an HTTPS endpoint	POST /api/v1/notify with reply_to	the HMAC-signed webhook
cron / CI	npx pidge-cli message/important	usually nothing — fire-and-forget

Three rules of thumb, whatever the framework:

1. Set correlation_id to your task id — sends become idempotent and every reply routes itself back to the task.
2. Read the manifest at startup (GET /api/v1/manifest) — fields, action catalog and guarantees are versioned there; new server features are usable via raw fields the day they ship. There’s also a plain-text operating guide an agent can read directly — https://api.pidge.sh/agent-setup — but the manifest stays the contract.
3. One consumer per channel — if two processes might read the same channel’s messages, give each its own channel (or let one consume and the others catchup).

For agents that speak “skills”, npx pidge-cli skill install --target agents writes an AGENTS.md teaching the model the send/wait/listen vocabulary.