SeenRelay

SeenRelay

Decide when you actually need to look again.

SeenRelay measures repeated expensive read-only execution around agents and distributed software. It prefers local/private and source/provider-native controls first, preserves authoritative execution while measuring, and keeps only paths that earn a USE verdict. Start locally with npx seenrelay scan; if no candidate exists or a stronger native control already wins, stop there. DO NOT USE and INSUFFICIENT EVIDENCE are valid outcomes.

Currently free · no account · no SeenRelay API key required.

Terminology: a Savings Report (machine label: Verified Savings Record) is measurement evidence for avoided work and cost provenance. It is not an invoice, bill, charge or payment receipt. Some SDK/API identifiers retain receipt wording for backward compatibility only.

SeenRelay itself requires no account or API key. A third-party client, directory, gateway, or assistant may require its own account to use that third-party service; that is not a SeenRelay access requirement. The canonical direct MCP endpoint is https://seenrelay.com/mcp.

See measured proof before you install

The Proof Atlas shows where SeenRelay has already reduced real provider work under frozen semantic contracts:

• 8-agent first-party operating workload: eight department agents across two tenant identities kept their independent role analyses while sharing approved current evidence. Paid web-search actions fell 13 → 4 and measured provider cost fell $0.16499684 → $0.05560972 ($0.10938712 gross avoided; 66.30% reduction for this run). One tenant was real SeenRelay operating work; the second was an explicitly synthetic external-client rehearsal with real provider execution.
• real live-event monitoring: four paid downstream briefings became one on unchanged event state across 3/3 paired runs (79.61% mean gross reduction), while a changed event fingerprint forced fresh work;
• 64 GB hosted compute: $1.9241253 → $0.4820025 for four compatible intents ($1.4421228 avoided; 74.95% gross reduction) — mechanism-only for the exact SHA-256 task because local computation wins Tool Necessity;
• real retail monitoring: 4 → 1 Firecrawl credits across 3/3 unchanged-state trials (75% reduction) under its bounded contract.

The 8-agent result is first-party operating evidence, not external customer adoption, customer ROI or net customer savings; local coordination/integration overhead was not monetized. Other Proof Atlas rows include controlled mechanism results, and a high reduction does not automatically mean the expensive tool was the best baseline. Proof Atlas exposes baseline quality separately. For example, the 64 GB SHA-256, fixed-rule weather, fixed-string LiteLLM, and PyPI-version web-search tests are mechanism-only because cheaper local/source-native solutions exist for those exact benchmark tasks. Negative evidence is published too.

Human-readable proof: https://seenrelay.com/proof Machine-readable proof: https://seenrelay.com/proof.json

What SeenRelay is deciding

SeenRelay is designed around one question: “I already know X — do I need to pay to validate X again now?”

CHECK is not a lookup for somebody else's raw result. The caller supplies the known value, deterministic source-backed fact identity and its own freshness window. SeenRelay reports compatible recent evidence; the caller keeps authority over whether to validate again.

For a small public set of source-backed facts, use the canonical starter descriptors at https://seenrelay.com/starter-facts.json. They publish identity metadata only — no observed values, no recommended TTL and no reuse authorization. Full decision-layer rationale: docs/DECISION_LAYER.md.

Not sure whether SeenRelay fits? Ask for a workload audit

If you have a public workload that appears to repeat expensive read-only work, you can ask for a native-first prescreen before installing anything:

https://github.com/ovladon/seenrelay/issues/new?template=audit-my-workload.yml

The first answer may be REJECT BEFORE COLLECTION, MEASURE IN SHADOW, or INSUFFICIENT EVIDENCE. A local, source-native, or provider-native control winning is a successful result.

Fastest start: give SeenRelay to your coding agent

Claude Code can install SeenRelay persistently from this repository's validated self-hosted marketplace:

claude plugin marketplace add ovladon/seenrelay

claude plugin install --scope user seenrelay@seenrelay

This direct-install path is repository-hosted and does not imply Anthropic marketplace approval. It does not automatically attach the hosted MCP endpoint or enable reuse.

GitHub Copilot CLI can discover the existing portable Agent Plugins package from this repository's self-hosted marketplace:

copilot plugin marketplace add ovladon/seenrelay

copilot plugin install seenrelay@seenrelay

The Copilot route is optional and uses the repository's existing skill and MCP metadata. It does not enable reuse automatically. Marketplace publication does not imply listing in a curated or default catalog, and end-to-end Copilot installation is not yet independently verified.

Other Agent Skills clients can use the canonical domain:

npx skills add https://seenrelay.com --skill seenrelay --yes

Then ask it:

Run a SeenRelay shadow audit on this project. Find repeated expensive read-only validations, preserve every authoritative call, measure stronger local/source/provider-native controls first, do not enable reuse, and return USE / DO NOT USE / INSUFFICIENT EVIDENCE for each measured workload.

Or use the developer paths below. Full audit method: docs/SHADOW_AUDIT.md.

Install: npm install seenrelay · pip install seenrelay · client v0.2.30 · currently free · no account/API key.

Zero-code local prescreen

Before changing application code, ask whether the repository even contains a plausible recurring expensive read-only validation path:

npx seenrelay scan

The scan is local-only: it does not contact SeenRelay, upload source code or modify the project. It reports only pre-evidentiary states such as CANDIDATE_FOR_SHADOW_MEASUREMENT, NATIVE_CONTROL_FIRST, NEEDS_RUNTIME_EVIDENCE and NO_ELIGIBLE_CANDIDATE_FOUND. Static analysis cannot return USE or authorize reuse.

Optional GitHub Actions cost prescreen

Teams can expose the same local-only static prescreen in CI without a SeenRelay account or API key:

- id: seenrelay

uses: ovladon/seenrelay-cost-prescreen@v1

The action runs on the GitHub runner, does not contact the SeenRelay service, does not upload source code to SeenRelay, and cannot enable reuse or return a USE verdict. It produces a team-visible job summary plus machine outputs for the static status and next non-mutating decision.

Free shadow audit: measure without changing application behavior

Ambient wraps an existing MCP-style client in local shadow mode. The authoritative call still runs; SeenRelay measures exact repetition and produces a local report.

JavaScript / TypeScript:

npm install seenrelay

import { ambientMcpClient } from 'seenrelay/ambient';

const client = ambientMcpClient(rawMcpClient); // use client.callTool(...) normally console.log(client.seenRelayAmbient.getReport());

Python:

pip install seenrelay

from seenrelay_ambient import ambient_mcp_client

client = ambient_mcp_client(raw_mcp_client)

await client.call_tool(...) normally

print(client.get_report())

Run the existing workload and inspect the report before enabling any bounded reuse. Shared CHECK remains optional and off by default in Zero-State.

SeenRelay is a provider-independent reuse layer for repeated read-only validation. It has exactly two hosted domain operations: CHECK and OBSERVE, and reports recent observations rather than universal truth.

Current JavaScript/TypeScript and Python clients include multi-signal shared-evidence assurance helpers, deterministic Fact Coordinate Kit v1 and provider-independent Zero-State. Python Zero-State supports explicit read-only in-flight/local reuse, caller-owned private L1 and source-native conditional validation before authoritative fallback. The classic Python API and Python Ambient adapters remain shadow-first by default. Shared evidence is explicit caller policy, does not prove truth or independent real-world actors, and MCP/OpenAPI coordinates are local repetition keys unless a stable source-native locator supports a shared fact descriptor. Provider-specific adapters are optional.

What it can avoid

Even with no shared observation:

• simultaneous identical eligible calls can be coalesced in-process;
• completed read-only results can be reused only inside an explicit caller-defined freshness window;
• optional encrypted caller-owned L1 storage can reuse values across workers or restarts;
• ETag / Last-Modified can support source-native conditional confirmation without a shared CHECK;
• shared CHECK is optional in Zero-State and is not placed on the hot path merely because SeenRelay is installed;
• after a genuinely fresh independent validation, OBSERVE can add evidence that may help later callers.

Access is currently free and requires no account or API key.

Start here

• Decision layer: docs/DECISION_LAYER.md
• Canonical starter facts: https://seenrelay.com/starter-facts.json
• Free shadow audit: docs/SHADOW_AUDIT.md
• Claude Code persistent install: claude plugin marketplace add ovladon/seenrelay then claude plugin install --scope user seenrelay@seenrelay
• Other coding-agent install: npx skills add https://seenrelay.com --skill seenrelay --yes
• Public install: npm install seenrelay or pip install seenrelay
• JavaScript / TypeScript Zero-State: clients/typescript/README.md
• Fleet economics: https://seenrelay.com/economics
• Client overview: clients/README.md
• Integration choices and MCP setup: docs/CLIENTS.md
• Quickstart: docs/QUICKSTART.md
• Protocol contract: docs/PROTOCOL.md
• Web quickstart: https://seenrelay.com/quickstart
• Web client integrations: https://seenrelay.com/clients
• MCP endpoint: https://seenrelay.com/mcp
• Official MCP Registry: io.github.ovladon/seenrelay
• OpenAPI: https://seenrelay.com/openapi.json
• Machine descriptor: https://seenrelay.com/service.json
• Machine-oriented index: https://seenrelay.com/llms.txt

How it works

For eligible JavaScript/TypeScript Zero-State calls, the preferred order is:

1. exact in-process reuse / coalescing when safe;
2. optional caller-owned private reuse;
3. source-native conditional confirmation when available;
4. optional shared SeenRelay CHECK when configured and useful;
5. the application's original validation as fallback;
6. OBSERVE only after a fresh independent validation that is eligible for contribution.

For direct REST/MCP or the classic wrapper, CHECK and OBSERVE remain available exactly as before.

Possible CHECK statuses are SAME_OBSERVED, CHANGED_OBSERVED, CONTESTED, STALE, and UNKNOWN.

SAME_OBSERVED means the same value was recently observed for the same deterministic fact identity. It is not a truth verdict. The consuming agent decides whether the evidence is sufficient for its own policy.

JavaScript / TypeScript Zero-State

import { SeenRelayZeroState } from 'seenrelay/zero-state';

const edge = new SeenRelayZeroState({ localMaxAgeMs: 30_000 });

const result = await edge.guard({ coordinate: { tool: 'catalog.read', arguments: { id: 42 } }, validate: async () => expensiveRead() });

console.