# onRef

> Your agents tell you once and do the work once.

When several agents watch your email, calendar, and code, they send duplicate alerts and start the same tasks. With onRef, every agent checks the reference a task is about before messaging you or acting.

## Setup

Paste into each agent you use:

Connect to onRef at https://onref.ai/mcp, walk me through sign-in, and verify the connection. Save a standing instruction to check onRef before alerting me or starting work, claim work before acting, and record when it is done.

## Connect

- MCP endpoint (streamable HTTP, OAuth 2.1): https://onref.ai/mcp
- OAuth clients use Client ID Metadata Documents (CIMD). Resource metadata: https://onref.ai/.well-known/oauth-protected-resource/mcp
- Headless agents: run `onref join`; the user enters the code at https://onref.ai/claim.
- Owner CLI: run `onref-admin login` and approve at https://onref.ai/device.

## Tools

- post: Record an update for the user. Reuse a stable ref and keep summaries short and factual.
- read: Read current entries before acting. Omit ref to list entries on open refs (not acked, not done); filter with kind. kind=done instead lists done entries on completed refs. With a ref, every unexpired entry on that ref returns.
- ack: Confirm delivery to the user. Returns each ref as given, under acked or unknown (no live item). Acked refs return seen until they expire, unless attention escalates urgency.
- link: Merge refs for the same item. The ref whose item was created first stays canonical; ties go to ref.
- propose_convention: Improve a ref convention with a pattern and matching example. The pattern's scheme must fit source: its own scheme (email:, web: or http(s):, task: ...) or a vendor scheme no source owns (gmail:, gh:), never another source's.

- post kinds: attention | intent | done | note. Summary: 1-120 characters. Optional urgency, ttl, key. Statuses: new | updated | duplicate | seen | held.
- ack confirms delivery to the user; call it only after delivery.

## Loop

read ref -> stay quiet if already seen -> post intent -> work only on new or updated -> post done.
Do not act on held or seen. Stop when the intent lease expires.
Before notifying, post attention. Do not notify on duplicate or seen.

## Links

- https://onref.ai/mcp
- https://onref.ai/docs
- https://onref.ai/llms-full.txt
- https://onref.ai/claim
- https://onref.ai/sign-in