Narrator

Read TypeScript and JavaScript as plain English sentences, generated deterministically without an LLM.

Read code in plain English

Narrator turns TypeScript and JavaScript into clear sentences, deterministically and without an LLM. It runs on your server or in the browser.

Get startedBrowser extension

What it is

Narrator is an SDK, published under the @usenarrator/* scope, that turns source files and diffs into English sentences. Every phrase comes from a syntax node and a rule, so the same code always reads the same way, and you can point at the rule that produced any sentence.

Programmatic, not generative

Narrator uses rules, not a language model, so the same code always produces the same English. It is fast enough to narrate a whole pull request when the page loads.

Runs anywhere

It uses the native oxc parser on Node and Bun, and a WASM build of the same parser in browsers, extension workers and edge runtimes.

Pluggable on three axes

You can add source languages (TypeScript and JavaScript today), output languages (English today), and library plugins. Twenty-five ship today, from React and Next.js to Drizzle, Stripe and Temporal.

Why it exists

More and more code is written quickly, often with help from AI tools, and someone still has to review it. Reading a diff line by line is slow, and a summary written by a model can sound right while missing the one condition that matters. Narrator sits between the two. It reads every statement, so nothing is skipped, and it says what the code does in sentences you can skim. When the English looks wrong, the code usually is too.

It also helps people who read code less often than they write it: a product manager checking what a pricing rule really does, a new teammate finding their way around, or a reviewer working in a library they don’t know well.

A 30-second demo

The narrator CLI narrates files, directories and git diffs. Point it at a file:

billing.ts

export async function renewSubscription(subscription: Subscription, now: Date) {
  if (subscription.status === "canceled") return;
  const plan = plans.find((p) => p.id === subscription.planId);
  if (!plan) throw new NotFoundError("Unknown plan");
  for (const seat of subscription.seats) {
    if (seat.expiresAt < now) await releaseSeat(seat);
  }
  await sendReceipt({ to: subscription.ownerEmail, amount: plan.price });
}

narrator billing.ts --plain

To renew subscription (async), given subscription (Subscription) and now (Date):
  If subscription's status is "canceled", stop here.
  Let plan be the first p in plans where p's ID is subscription's plan ID.
  If plan is missing, fail with a not found error: "Unknown plan".
  For each seat in subscription's seats:
    If seat's expires at is before now, release seat (seat).
  Send receipt (to: subscription's owner email and amount: plan's price).

A few things to notice: ownerEmail became “owner email” (identifiers are split into words, and abbreviations expand through a glossary), the find callback became “the first p in plans where…”, and the guard clause became a single “If …, stop here.” Nothing was summarized away, because Narrator narrates every statement instead of paraphrasing the whole function.

Reading diffs on GitHub

The browser extension uses the same engine to replace GitHub’s diff rows with English, so you can review what a pull request does before you read how it does it.

The extension on a public pull request. Each changed declaration gets its own block, with added sentences in green.

Where to go next

Getting started

Narrate a file and a diff from your own code in five minutes.

How it works

Follow a statement from source code through the engine and plugins to the finished sentence.

Browser extension

Read GitHub pull requests in English, inline, in either split or unified view.

Plugins

Add plugins so that calls to your libraries read naturally.