Your backend reports what happened (order.shipped, payment.failed). Cue decides whether that is worth a notification, renders it in the person's language, picks the time and the route, and hands a finished message to the delivery you connect: your own sending service through a signed webhook, or a bundled connector.

• Rules and policy in one place. JSON Logic rules map events to templates; every message, whether triggered by a rule, sent directly or broadcast, passes the same checks: unsubscribes, muted channels, frequency caps, cooldowns and quiet hours in the recipient's own time zone, checked again right before sending.
• Fewer messages. Digests turn a burst of events into one message per window or one per day at a local time, and fatigue backs off from people who stopped engaging.
• People in control. A hosted preference page (or a JSON API for your own), RFC 8058 one-click unsubscribe, and a consent ledger of every change.
• Answers. Every event records which rules matched and why; every message records its status and the reason it was suppressed or failed.
• Limits for automated senders. Agents and other services get per-person budgets, importance ceilings and human approval before anything goes out.

curl -X POST https://cue.example.com/v1/events \
  -H "Authorization: Bearer $CUE_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "order.shipped", "recipient": "customer-42",
       "data": {"order_id": "1001"}, "idempotency_key": "order-1001-shipped"}'

Your delivery endpoint then receives a signed, fully rendered message:

{
  "id": "01a1…",
  "channel": "push",
  "address": "<device token>",
  "locale": "en",
  "importance": "normal",
  "expires_at": null,
  "content": {"title": "Your order is on its way", "body": "Order 1001 ships today.",
              "url": "https://shop.example/orders/1001"},
  "metadata": {"cue_message_id": "01a1…", "cue_tracking_token": "…"},
  "links": {"preferences": "https://cue.example.com/preferences/…"}
}

Who it's for

For teams that already send push, e-mail, SMS or chat messages from their own code and want the decisions (whether, when, how often, over which route, in which language) made in one place, stored, and explainable, on their own infrastructure.

Not for you (yet) if you need:

• an in-app inbox or notification feed: planned, not built;
• an admin UI: today you configure Cue through the HTTP API, the CLI and cue.toml;
• APNs, Amazon SES, Resend or Slack connectors: planned. Today's connectors are FCM, Twilio, SMTP, Telegram, a signed webhook and console, plus any you write;
• a hosted service: Cue is self-hosted only;
• a visual journey builder for marketing campaigns: not planned.

See the roadmap.

Quick start

With Docker Compose (PostgreSQL, an API and a worker; messages go to the worker's log):

git clone https://github.com/murtazox04/Cue && cd Cue
docker compose up --build -d
docker compose exec api cuectl keys create admin
docker compose logs -f worker

Or with Python 3.12+ and SQLite, in a virtual environment:

python -m venv .venv && . .venv/bin/activate
pip install cue-notify
export CUE_WORKER__EMBEDDED=true
export CUE_CHANNELS__PUSH__PROVIDER=console CUE_CHANNELS__SMS__PROVIDER=console
cuectl db upgrade && cuectl keys create admin && cuectl serve

keys create prints an API key once; keep it as CUE_API_KEY. Then follow the getting-started guide to create a template and a rule and send an event that shows up in the log.

To try it without installing anything, with uv:

CUE_WORKER__EMBEDDED=true CUE_CHANNELS__PUSH__PROVIDER=console \
  CUE_CHANNELS__SMS__PROVIDER=console uvx cue-notify serve --migrate

and, in a second terminal in the same directory (both use ./cue.db), uvx cue-notify keys create admin.

Bring your own delivery

Each route (push, sms, email, ops-alerts…) is backed by a connector:

Connectors are configuration, not code changes: swap SMS vendors without touching a rule.

AI agents and other automated senders

• Agents as senders. Each agent gets its own key with a per-person attention budget, an importance ceiling and, where you want it, human approval before anything goes out. Agent keys cannot read or change people's profiles, and cannot approve anything. See agents.
• Ask a person first. Before a risky action (a refund, a deletion, a mass e-mail), an agent calls POST /v1/approvals or the request_approval MCP tool. Cue tells the reviewers on their own channels with a one-time link and reports the decision back, with bridges for LangGraph, Pydantic AI, CrewAI Flows and Dapr Agents. See approval requests.
• MCP server. uvx cue-notify mcp gives Claude, Cursor or your own agent tools to notify people and inspect delivery, under the same policy and audit trail. See AI agents (MCP).
• Screening (optional, off by default, experimental). With [screening] enabled = true and a TypeSafe API key, a decision model (Jev) reads each agent message before it is sent: pressure, deception or leaked secrets hold it for a person, and overstated importance is lowered. Built against TypeSafe's published API; not yet proven in production. Your own backend's messages are never screened.
• Coding agents. cue-hook lets OpenHands and Claude Code tell you when they finish or wait for input. See coding agents.
• Claude Code plugin. /plugin marketplace add murtazox04/Cue, then /plugin install cue@cue, adds a skill for integrating Cue into an application.

Also

• SDKs. pip install cue-notify-client and npm install cue-client, both with webhook signature verification. See SDKs.
• Engagement tracking. Delivered, opened, clicked, converted; client apps report with a per-message token, no API key needed.
• Broadcasts. Audience filters, resumable batches, pause/resume/cancel without double sends.
• Compliance. US texting hours and state caps for marketing texts, STOP/START replies, and opt-in records with the disclosure shown. See compliance.
• Runs on your database. An API process and a worker process (or the worker embedded in the API for small installs), with PostgreSQL or SQLite. No Redis or message broker: the durable job queue lives in the database. Schedule cuectl prune yourself for retention.
• Observable. Per-rule event outcomes, status reasons, Prometheus metrics, JSON logs.
• Docs for tools. llms.txt and AGENTS.md.

How Cue compares

How it works

flowchart LR
    E[POST /v1/events] --> R{Rules}
    R --> P[Policy<br/>unsubscribe · caps · cooldown · quiet hours]
    P --> T[Template<br/>locale · route variants]
    T --> Q[(Queue)]
    Q --> A[AI rewording<br/>optional]
    A --> C{Your delivery<br/>webhook · connectors}

Configuration

Environment variables (CUE_SECTION__KEY) or a cue.toml:

[database]
url = "postgresql+asyncpg://cue:secret@db/cue"

[api]
public_url = "https://cue.example.com"   # needs CUE_API__SECRET_KEY

[channels.push]
provider = "webhook"
url = "https://notifications.internal.example/push"   # secret from CUE_CHANNELS__PUSH__SECRET

[channels.sms]
provider = "twilio"
account_sid = "AC…"
from_number = "+15550100"   # auth token from CUE_CHANNELS__SMS__AUTH_TOKEN

See the configuration reference, deployment and examples/cue.toml.

Project status

Cue is in early development (0.x): the model and API are stable in shape but may still change before 1.0; each release's changelog says what to do when upgrading. See the roadmap for what comes next. Feedback and contributions are welcome; see CONTRIBUTING.md.

License

MIT