@@ -0,0 +1,4 @@
+node_modules/
+web/dist/
+*.log
+.DS_Store
@@ -0,0 +1,5 @@
+ReadyCode Reader
+Copyright 2026 ReadyCode (https://readycode.ai)
+
+This product includes software developed by ReadyCode.
+It uses pdf.js (Mozilla Foundation, Apache-2.0).
@@ -0,0 +1,123 @@
+# ReadyCode Reader
+
+**Ask huge PDFs, Word documents and spreadsheets specific questions. Your AI gets only the passages that answer, with citations, instead of reading the whole file.**
+
+ReadyCode Reader is a free, open-source [MCP](https://modelcontextprotocol.io) server for Claude Code, Cursor, Codex and any other MCP client, and it also runs in a browser. It reads a file once on your computer. Then, for each question, it returns **only the passages that answer it**, with where they came from, plus checks on that evidence:
+
+- **Not in the document:** if the file can't answer, your AI is told `not_in_document` instead of getting passages to guess from.
+- **Passages disagree:** if two passages give different values, your AI is told to report both.
+- **Hidden instructions:** passages that try to instruct the AI reading them are flagged and treated as data only.
+- **Needs a calculation:** spreadsheet questions like "how many…" or "list every…" are flagged instead of being estimated from a few rows.
+
+## Standard AI vs Reader
+
+Same questions, same AI, fresh sessions: once the normal way (the AI reads the file with its own tools), once with Reader.
+
+| Test | Standard | With Reader |
+|---|---|---|
+| **Codex**, 200-page NASA PDF, 8 questions | 8/8 correct · **913,468 tokens** · about 3 min | 8/8 correct · **41,997 tokens** · about 20 s |
+| **Grok 4.7 in Cursor**, same PDF | 8/8 correct · read the whole book (about 45,000 tokens) · about 4 min | 8/8 correct · **4,693 tokens** of evidence · about 2 min |
+
+Token counts for Codex come from Codex's own session log. That's **95% fewer tokens and about 9× faster** for the same answers. Most of the saving comes from steps: an agent re-sends its whole conversation at every step, and with Reader it needed 2 steps instead of 17.
+
+## Measured on large files
+
+Every expected answer below was checked by code against the file, and every "not in the document" question was checked to be truly absent. Scripts and question files are in [`benchmark/`](benchmark/).
+
+| File | Size as text | Correct | Tokens returned | Time for all questions | Check cost |
+|---|---|---|---|---|---|
+| NASA *Earth at Night* (PDF, 200 pages) | 42,282 tokens | 8/8 | 3,487 | 2.3 s | $0.0027 |
+| Australian Universities Accord Final Report (Word) | 263,487 tokens | 11/11 | 15,790 | 1.7 s | $0.0042 |
+| Sample contacts workbook (Excel, 100 MB, 1.1 million rows) | 271,424,159 tokens | 11/11 | 2,323 | 0.9 s | $0.0038 |
+
+The Word report is larger than many AI context windows, and the spreadsheet is more than a hundred times larger than any. Each set includes questions the file cannot answer; Reader said `not_in_document` every time. On the spreadsheet it also declined 3 counting and ranking questions rather than guess.
+
+Honest limits of these results: they are our own runs on three files, not an independent study, and head-to-head runs against a standard AI exist so far only for the PDF.
+
+## Install (MCP)
+
+You need [Node.js](https://nodejs.org) 20 or newer and an [OpenRouter](https://openrouter.ai) API key, set once as the environment variable `OPENROUTER_API_KEY`.
+
+**Claude Code**
+
+```bash
+claude mcp add readycode-reader -- npx -y @readycode/reader
+```
+
+**Cursor**: add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "readycode-reader": { "command": "npx", "args": ["-y", "@readycode/reader"] }
+  }
+}
+```
+
+**Codex**: add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.readycode-reader]
+command = "npx"
+args = ["-y", "@readycode/reader"]
+```
+
+**Claude Desktop**: add the same entry as Cursor under `mcpServers` in `claude_desktop_config.json`.
+
+Restart your tool and check that `readycode-reader` shows three tools: `load_document`, `ask_document` and `list_documents`.
+
+## Use
+
+Ask your AI something like:
+
+> Load `C:\Docs\contract.pdf` with readycode-reader and tell me everything it says about late fees and termination.
+
+Your AI loads the file, sees its contents, asks Reader specific questions and answers from the cited passages. You don't need to know the file or write special questions.
+
+- `load_document(path)` reads a PDF, Word (.docx), Excel (.xlsx), TXT, Markdown, CSV or JSON file. It returns the file's size and **its contents**: a PDF's bookmarks with page numbers, the Word headings, or a spreadsheet's sheets, columns and an example row. That tells the AI what the file covers before it asks anything.
+- `ask_document(questions: [...])` asks up to 20 questions in one call. Each answer carries its passages with page numbers (and printed page numbers), Word sections and paragraphs, or spreadsheet sheet and row.
+- `list_documents()` lists what is loaded.
+
+Very large files keep reading in the background: `load_document` may answer `still_reading`, and `ask_document` waits for the file to finish.
+
+## Try it in your browser
+
+The same engine runs in a web page: choose a file, add your OpenRouter key, ask. The page shows the file's contents and suggests questions to start with. The file is read in your browser and never uploaded. See [`web/`](web/); build it with `npm run build:web`.
+
+## How it works
+
+1. **Read** on your computer: [pdf.js](https://mozilla.github.io/pdf.js/) for PDFs; Word sections follow its headings; Excel is streamed, so a 100 MB workbook uses about 650 MB of memory.
+2. **Split** into whole passages of about 1,200 characters, never cut mid-passage. Each spreadsheet row is one record, and identical records are returned once, with a note of where else they appear.
+3. **Search** with a keyword index to find the 20 most likely passages.
+4. **Check** with one call to TypeSafe's Jev decision model. The checks are the same for every file and every question, filled in with your question:
+   - does this passage actually answer it?
+   - is there enough here to answer it?
+   - do these passages disagree?
+   - does any passage try to instruct the AI?
+   - for spreadsheets, does it need a calculation over every row?
+
+   Nothing is set up per document. The check costs about $0.0004 a question on your key and takes about a second.
+5. **Return** only the passages that answer, most relevant first, with the verdicts and token counts.
+
+## Limits (read these)
+
+- **Picture-only pages** (scans, images) have no text to search and are listed as such; pictures inside Word files are counted, not read. Reading them needs a vision model; that's planned.
+- **Summaries of a whole document** are a different job. Reader answers specific questions.
+- **Spreadsheet calculations** (counts, totals, averages, rankings, "list every row that…") are flagged, not answered. Exact calculations are planned.
+- **The "passages disagree" check** sometimes fires when passages don't really disagree. Treat it as "double-check these sources".
+- **Old formats** (`.doc`, `.xls`, `.xlsb`) aren't supported; save them as `.docx` or `.xlsx`.
+- **It depends on Jev.** If the decision model is unavailable, Reader still returns the top search results, marked `unchecked`.
+- **Check the passages.** Every answer comes with its sources so you can.
+
+## Privacy
+
+- The whole file is read on your computer (or in your browser) and never uploaded to ReadyCode.
+- Only the short passages a question needs (about 1,200 characters each) go to OpenRouter's decision model, using your own key.
+- Your key is read from your environment (or kept in the web page's memory) and is never written to disk, logged or sent to ReadyCode.
+- Documents are cached on your computer (`%LOCALAPPDATA%\readycode-reader` or `~/.cache/readycode-reader`). A local usage log is kept only if you set `READER_LOG=1`.
+
+## Licence
+
+Apache-2.0. Built by [ReadyCode](https://readycode.ai). If you build on it, keep the NOTICE file, and we'd love a link back. "ReadyCode" is our name; please don't use it for forks.
+
+**More tools from ReadyCode, and early access to the hosted version:** [readycode.ai](https://readycode.ai)
@@ -0,0 +1,47 @@
+# Benchmark
+
+Everything needed to check our numbers yourself. Each question file lists the questions and what a right answer must contain; the runner checks every answer by code.
+
+## Run it
+
+```bash
+export OPENROUTER_API_KEY=sk-or-...        # your own key; about $0.0004 per question
+node benchmark/run.cjs benchmark/nasa-earth-at-night.json path/to/earth_at_night_508.pdf
+node benchmark/run.cjs benchmark/universities-accord-word.json "path/to/Australian Universities Accord - Final Report.docx"
+node --max-old-space-size=8192 benchmark/excel-lookups.cjs path/to/workbook.xlsx
+```
+
+Before asking anything, the runner confirms that the file really contains every expected answer and really lacks the words of every "not in the document" question, so a wrong file or an unfair question stops the run.
+
+A question passes when:
+
+- **answer questions:** Reader's verdict is `answer_from_passages` (or `low_confidence`) and the passages it returned contain every expected phrase;
+- **not-in-the-document questions:** the verdict is `not_in_document`;
+- **calculation questions** (spreadsheets): the verdict is `needs_calculation`.
+
+## The files
+
+- **NASA *Earth at Night*** (2019, 200-page PDF, NP-2019-07-2739-HQ): free from nasa.gov. Questions: [`nasa-earth-at-night.json`](nasa-earth-at-night.json), 6 answerable and 2 that the book cannot answer.
+- **Australian Universities Accord – Final Report** (Australian Government, Word .docx, about 263,000 tokens): published by the Department of Education. Questions: [`universities-accord-word.json`](universities-accord-word.json), 9 answerable and 2 that the report cannot answer.
+- **A 100 MB contacts workbook** (1.1 million rows of fake people generated with the Faker library, 4 sheets, columns Name, Email, Phone, Address, Company, Text, Description, Job Title). [`excel-lookups.cjs`](excel-lookups.cjs) picks rows at random (fixed seed) and computes each expected answer over every row: 5 lookups by name, 2 reverse lookups (by email and by phone), 1 name that isn't in the file, and 3 counting or ranking questions. It works on any workbook with those columns.
+
+## Results (30 September 2026, Jev `typesafe/jev-1.13`)
+
+| File | Correct | Document tokens | Tokens returned | Load | All questions | Check cost |
+|---|---|---|---|---|---|---|
+| NASA PDF | 8/8 | 42,282 | 3,487 | 0.6 s | 2.3 s | $0.0027 |
+| Word report | 11/11 | 263,487 | 15,790 | under 1 s (cached) | 1.7 s | $0.0042 |
+| Excel workbook | 11/11 | 271,424,159 | 2,323 | 14.3 s | 0.9 s | $0.0038 |
+
+## Standard AI vs Reader (NASA PDF)
+
+The same 8 questions were given to each AI twice, in fresh sessions: once reading the PDF with its own tools, once through Reader. The prompts didn't say what Reader was; they asked the AI to measure its own usage.
+
+| AI | Standard | With Reader | Source of the numbers |
+|---|---|---|---|
+| Codex (ChatGPT) | 8/8 · 913,468 tokens · 17 steps · about 3 min | 8/8 · 41,997 tokens · 2 steps · about 20 s | Codex session log |
+| Grok 4.7 (low) in Cursor | 8/8 · whole book read (about 45,000 tokens of text) · about 4 min | 8/8 · 4,693 tokens of evidence · about 2 min | Cursor's own report |
+
+Most of Codex's saving is cached tokens, which cost less, so the cost saving is smaller than the token saving: about 85% rather than 95%.
+
+Head-to-head runs for the Word and Excel files haven't been done yet.
@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+"use strict";
+// Builds a question file from any large people/contacts spreadsheet with
+// Name, Email, Phone, Address, Company and Job Title columns, with every
+// expected answer computed by code over all rows, then runs it.
+//   node --max-old-space-size=8192 benchmark/excel-lookups.cjs path/to/100mb.xlsx
+// The benchmark used a synthetic 100 MB sample workbook (fake people made
+// with the Faker library, 1.1 million rows in 4 sheets).
+const engine = require("../src/engine.cjs");
+const { run } = require("./run.cjs");
+
+(async () => {
+  const file = process.argv[2];
+  if (!file) { console.error("Usage: node benchmark/excel-lookups.cjs <workbook.xlsx>"); process.exit(2); }
+  if (!process.env.OPENROUTER_API_KEY) { console.error("Set OPENROUTER_API_KEY first."); process.exit(2); }
+  const t = await engine.readXlsx(file);
+  const N = t.rowStart.length - 1;
+  const row = (r) => { const o = {}; const h = t.sheets[t.rowSheet[r]].headers; for (let k = t.rowStart[r]; k < t.rowStart[r + 1]; k++) o[h[t.cellCol[k]]] = t.values[t.cellVal[k]]; return o; };
+  const where = (field, value) => { const out = []; for (let r = 0; r < N; r++) { const o = row(r); if (o[field] === value) out.push(o); } return out; };
+  let seed = 7;
+  const rnd = () => (seed = (seed * 1103515245 + 12345) % 2147483648) / 2147483648;
+  const pick = () => row(Math.floor(rnd() * N));
+  const people = [];
+  while (people.length < 5) { const o = pick(); if (o.Name && o.Phone && o.Company && o["Job Title"] && o.Email && o.Address) people.push(o); }
+  const asks = [["Phone", (n) => `What is the phone number of ${n}?`], ["Company", (n) => `Which company does ${n} work for?`], ["Job Title", (n) => `What is the job title of ${n}?`], ["Email", (n) => `What is the email address of ${n}?`], ["Address", (n) => `What is the address of ${n}?`]];
+  const questions = people.map((p, i) => ({ q: asks[i][1](p.Name), expect: [...new Set(where("Name", p.Name).map((o) => o[asks[i][0]]))] }));
+  const byEmail = pick(), byPhone = pick();
+  questions.push({ q: `Who has the email address ${byEmail.Email}?`, expect: [...new Set(where("Email", byEmail.Email).map((o) => o.Name))] });
+  questions.push({ q: `Whose phone number is ${byPhone.Phone}?`, expect: [...new Set(where("Phone", byPhone.Phone).map((o) => o.Name))] });
+  const trap = "Zebulon Quackenbush-Vantablack";
+  if (where("Name", trap).length) throw new Error("The trap name exists in this file.");
+  questions.push({ q: `What is the phone number of ${trap}?`, absent: ["Quackenbush"] });
+  const company = pick().Company, title = pick()["Job Title"];
+  questions.push({ q: `How many people in the file work at ${company}?`, calc: true, truth: where("Company", company).length });
+  questions.push({ q: `List everyone whose job title is ${title}.`, calc: true, truth: where("Job Title", title).length });
+  questions.push({ q: "Which company appears most often in the spreadsheet?", calc: true });
+  const r = await run({ document: { title: `${file.split(/[\\/]/).pop()}: ${N.toLocaleString("en")} rows` }, questions }, file);
+  for (const row of r.rows) console.log(`${row.ok ? "PASS" : "FAIL"}  ${row.question}\n      ${row.verdict}, ${row.evidence_tokens} tokens`);
+  console.log(`\n${r.document}\n${r.correct} correct | document ${r.document_tokens.toLocaleString("en")} tokens | evidence ${r.evidence_tokens.toLocaleString("en")} tokens | load ${r.load_seconds} s | ${r.rows.length} questions ${r.ask_seconds} s | checks $${r.check_cost_usd}`);
+  process.exitCode = r.rows.every((x) => x.ok) ? 0 : 1;
+})().catch((err) => { console.error(err.message); process.exit(1); });
@@ -0,0 +1,16 @@
+{
+  "document": {
+    "title": "Earth at Night (NASA, 2019), 200-page PDF",
+    "get_it": "NASA publication NP-2019-07-2739-HQ, free from nasa.gov (search \"Earth at Night ebook\"). The benchmark used earth_at_night_508.pdf."
+  },
+  "questions": [
+    { "q": "How many channels does the VIIRS instrument on Suomi NPP have, and what wavelength range do they cover?", "expect": ["22 channels", "412", "12,010"] },
+    { "q": "When did iceberg A-68 break away from the Larsen C ice shelf?", "expect": ["July 10 and July 12, 2017"] },
+    { "q": "What causes auroras?", "expect": ["charged particles"] },
+    { "q": "How many acres had the Okanogan Complex fire burned as of August 20?", "expect": ["91,314 acres"] },
+    { "q": "Over which periods was the book's cover image data acquired?", "expect": ["nine days in April 2012", "13 days in October 2012"] },
+    { "q": "How much did the Suomi NPP satellite cost to build?", "absent": ["cost"] },
+    { "q": "What had Shanghai's population grown to by 2016?", "expect": ["24 million by 2016"] },
+    { "q": "Which company built the VIIRS instrument?", "absent": ["Raytheon", "built by", "manufactured by"] }
+  ]
+}
@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+"use strict";
+// Runs a question file against a document and checks every answer by code.
+//   node benchmark/run.cjs benchmark/nasa-earth-at-night.json path/to/earth_at_night_508.pdf
+// Needs OPENROUTER_API_KEY. Each question costs about $0.0004 in checks.
+//
+// A question passes when:
+//   expect: every expected phrase is in the passages Reader returned (and the
+//           file really contains them, checked first);
+//   absent: Reader says not_in_document (and the file really lacks the words);
+//   calc:   Reader says needs_calculation.
+const fs = require("fs");
+const path = require("path");
+const engine = require("../src/engine.cjs");
+
+const flat = (s) => String(s).replace(/\s+/g, " ");
+const has = (text, phrase) => flat(text).toLowerCase().includes(flat(phrase).toLowerCase());
+
+async function documentText(file) {
+  const ext = path.extname(file).toLowerCase();
+  if (ext === ".xlsx" || ext === ".xlsm") {
+    const t = await engine.readXlsx(file);
+    return t.values.join("\n");
+  }
+  return (await engine.readPages(file)).map((p) => p.text).join("\n");
+}
+
+async function run(spec, file) {
+  const text = await documentText(file);
+  for (const q of spec.questions) {
+    for (const phrase of q.expect || []) if (!has(text, phrase)) throw new Error(`The file does not contain "${phrase}" (question: ${q.q}). Wrong file?`);
+    for (const word of q.absent || []) if (new RegExp(`\\b${word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i").test(flat(text))) throw new Error(`The file does contain "${word}", so "${q.q}" is not a fair not-in-document test.`);
+  }
+  let cost = 0;
+  const reader = engine.createReader({ log: (row) => { cost += row.check_cost_usd || 0; } });
+  let t0 = Date.now();
+  const loaded = await reader.load(file);
+  const loadSeconds = (Date.now() - t0) / 1000;
+  t0 = Date.now();
+  const res = await reader.ask({ document: loaded.document, questions: spec.questions.map((q) => q.q) });
+  const askSeconds = (Date.now() - t0) / 1000;
+  let pass = 0;
+  const rows = res.answers.map((a, i) => {
+    const q = spec.questions[i];
+    const got = a.passages.map((p) => p.text).join("\n");
+    const ok = q.absent ? a.verdict === "not_in_document"
+      : q.calc ? a.verdict === "needs_calculation"
+        : ["answer_from_passages", "low_confidence"].includes(a.verdict) && q.expect.every((phrase) => has(got, phrase));
+    pass += ok;
+    return { ok, question: q.q, verdict: a.verdict, evidence_tokens: a.evidence_tokens };
+  });
+  return { document: spec.document.title, correct: `${pass}/${rows.length}`, document_tokens: res.answers[0].document_tokens, evidence_tokens: res.total_evidence_tokens, load_seconds: Number(loadSeconds.toFixed(1)), ask_seconds: Number(askSeconds.toFixed(1)), check_cost_usd: Number(cost.toFixed(4)), rows };
+}
+
+if (require.main === module) {
+  const [specFile, file] = process.argv.slice(2);
+  if (!specFile || !file) { console.error("Usage: node benchmark/run.cjs <questions.json> <document>"); process.exit(2); }
+  if (!process.env.OPENROUTER_API_KEY) { console.error("Set OPENROUTER_API_KEY first."); process.exit(2); }
+  run(JSON.parse(fs.readFileSync(specFile, "utf8")), file).then((r) => {
+    for (const row of r.rows) console.log(`${row.ok ? "PASS" : "FAIL"}  ${row.question}\n      ${row.verdict}, ${row.evidence_tokens} tokens`);
+    console.log(`\n${r.document}\n${r.correct} correct | document ${r.document_tokens.toLocaleString("en")} tokens | evidence ${r.evidence_tokens.toLocaleString("en")} tokens | load ${r.load_seconds} s | ${r.rows.length} questions ${r.ask_seconds} s | checks $${r.check_cost_usd}`);
+    process.exitCode = r.rows.every((x) => x.ok) ? 0 : 1;
+  }).catch((err) => { console.error(err.message); process.exit(1); });
+}
+
+module.exports = { run, documentText };