# Cue

> Cue is the attention layer between software, AI agents and people. Applications and
> agents report events or send messages; Cue decides whether each notification is worth
> the person's attention, what to say (localised templates, optional AI wording with
> fact guardrails), when (quiet hours, digests, expiry), how important it is, and over
> which route. It then hands a rendered message to the delivery the application plugs in
> (a signed webhook, FCM, Twilio, SMTP or Telegram). Self-hosted, PostgreSQL or SQLite,
> MIT licensed, Python (FastAPI). Package: `cue-notify`; CLI: `cuectl`.

Key facts for integrating Cue:

- Authenticate with `Authorization: Bearer ck_…` (scoped API keys).
- Report events with `POST /v1/events` and an `idempotency_key`; rules decide what to send.
- Direct sends use `POST /v1/messages` with `template`, `channels`, `importance` and `expires_at`.
- Every outcome is recorded: messages carry `status` and `status_reason`.
- AI agents get their own keys, bound to an agent with a per-person budget and optional human approval.
- Approval requests: agents ask people before risky actions (`POST /v1/approvals`, MCP `request_approval`); decisions come back by signed callback; LangGraph, Pydantic AI, CrewAI and Dapr bridges in the Python SDK.
- Optional screening: a decision model (TypeSafe Jev) reads agent messages before delivery, holds risky ones for a person and lowers overstated importance.
- The MCP server runs with `uvx cue-notify mcp` (env `CUE_URL`, `CUE_API_KEY`).

## Docs

- [Getting started](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/getting-started.md): run Cue, create a key, send the first event
- [Events and rules](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/concepts/events-and-rules.md): events, JSON Logic conditions, priorities, delays, cooldowns, rollouts, dry runs
- [Templates](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/concepts/templates.md): localised Jinja2 content, channel overrides, variables, actions
- [Delivery policy](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/concepts/policy.md): the order of checks, categories, caps, quiet hours, fatigue
- [Importance and expiry](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/concepts/importance.md): importance levels, critical breakthrough, expiry, action buttons
- [Digests](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/concepts/digests.md): grouping bursts of events into one message, daily or weekly summaries at local time, AI summaries, thread grouping
- [Preference centre](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/concepts/preferences.md): hosted page, JSON API, RFC 8058 one-click unsubscribe, consent ledger
- [Approval requests](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/concepts/approvals.md): ask people to approve an agent's action; callbacks, CrewAI and Dapr
- [Agents](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/concepts/agents.md): attention budgets, importance ceilings, approval and screening for AI agents
- [Channels and connectors](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/concepts/channels.md): webhook payload and signature, FCM, Twilio, SMTP, Telegram
- [AI personalisation](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/concepts/ai.md): rewording with any Pydantic AI model under guardrails and a token budget
- [Engagement tracking](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/concepts/engagement.md): delivered, opened, clicked and converted signals
- [Broadcasts](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/concepts/broadcasts.md): one message to an audience in resumable batches

## Guides

- [AI agents (MCP)](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/guides/ai-agents.md): tools, transports and good practice for agents
- [Performance](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/guides/performance.md): cost per event, benchmark, scaling
- [Deployment](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/guides/deployment.md): PostgreSQL, workers, Docker, scaling
- [SDKs](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/guides/sdks.md): Python and TypeScript clients, webhook signature verification
- [Custom connectors](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/guides/custom-channels.md): writing a delivery plugin

## Reference

- [HTTP API](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/reference/api.md): endpoints and scopes (full OpenAPI at `/openapi.json` on any instance)
- [Configuration](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/reference/configuration.md): every setting, environment variables and `cue.toml`
- [CLI](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/reference/cli.md): `cuectl` commands

## Optional

- [Architecture](https://raw.githubusercontent.com/murtazox04/Cue/main/docs/architecture.md): components, job queue and design decisions
- [Integration skill](https://raw.githubusercontent.com/murtazox04/Cue/main/plugins/cue/skills/integrate-cue/SKILL.md): step-by-step instructions for coding agents adding Cue to an app