Skip to main content

Plainspeak

AI that reads the fine print for you.

Open source (MIT) · TypeScript · 11 core-logic unit tests, all green · FutureAI Global Hackathon 2026.

The problem

People sign leases, accept medical plans, and agree to terms of service they do not actually understand, because the language is built to be understood by the party that wrote it, not the person it affects. The comprehension gap is where the traps live: the non-refundable deposit, the auto-renewal, the clause that quietly makes you liable. Plainspeak is explicitly not legal, medical, or financial advice; it helps a person understand a document so they can ask the right questions before they agree.

Paste a document (a lease, a medical letter, a terms of service, a government form) and optionally say who you are. Plainspeak returns three things: the document in plain words at the reading level you pick (Like I am 10, Plain English, or Full detail), the specific clauses that affect you each flagged high, medium, or low so the traps surface first, and the exact questions to put to the landlord, clinician, or company before you agree. Three one-click examples (lease, medical letter, terms of service) are built in so anyone can see it work in seconds.

Quickstart

The core prompt-building and parsing logic is pure and unit-tested, so the tests run with no API key and no network. Node and pnpm; add an ANTHROPIC_API_KEY only when you want to run the live app.

Clone and install:

git clone https://github.com/OrionArchitekton/plainspeak
cd plainspeak
pnpm install

Command surface

  • pnpm dev: Next.js 15 App Router dev server at localhost:3000: paste a document, pick a reading level, and get the plain-words explanation, the clauses that affect you, and the questions to ask.
  • pnpm test: 11 Vitest unit tests over the pure prompt-building and defensive-parsing logic (lib/explain.test.ts). No network and no API key needed.
  • pnpm build: Production Next.js build. The Claude call runs server-side from a route handler so the API key is never exposed to the browser.
  • pnpm start: Serves the production build. Optional Upstash Redis rate limiting caps each client to 6 explanations per minute when configured; absent it, the API runs unthrottled.

Why it is different

  • Written for the reader, not the drafter: Most explainers summarize a document in the abstract. Plainspeak takes who you are as input and answers the only question that matters to you: which clauses affect me, and how badly. The output is ranked high, medium, or low so the deposit trap and the auto-renewal show up before the boilerplate.
  • A strict JSON contract, defensively parsed: The core is a single structured call to Claude with a fixed JSON output contract. The reply is parsed defensively in lib/explain.ts, so code-fenced or slightly malformed JSON still yields a clean result, and an out-of-range severity is coerced to a safe value rather than crashing the UI.
  • Honest about its limits: Plainspeak helps a person understand a document. It is explicitly not legal, medical, or financial advice, and it says so in the UI and inside the model guardrail. It does not store your documents; each request is processed, returned, and discarded, nothing is persisted.
  • Testable without a key: The prompt-building and parsing logic is pure, so 11 unit tests run with no network and no API key. The one place that touches Claude is a server-side route handler, keeping the key out of the browser and the risky part small and reviewable.

Links